Introduction

You'll need an API to access the RedeParede API. Get one here. API Key

Any questions please feel free to get in touch. api@redeparede.org

The only rules here are: 1) Do not use the API for malicious purposes and 2) You must include attribution (ie "This ad was originally posted at RedeParede.com.br")

The RedeParede API is implemented using XML over HTTP using the HTTP verbs (GET / POST / PUT / DELETE). The API has been engineered according to REST principles.

The xml representation of the exposed resources (Categories, Cities, Posts, Tags & Users) can all be viewed, using the GET action, by appending .xml to the URL. So /tags becomes /tags.xml to view the XML version.

All sample code is written as if it were accessing RedeParede Brasil at redeparede.com.br.

Authentication

When accessing any actions in the RedeParede API, which would require a user to be logged in on the main site, also requires them to be logged in when using the API. To login as a user using the API we use HTTP Basic Authentication.

Reading through the API

There are two kinds of read action through the API: 'List' and 'Show'. The list view returns a collection, whereas the show view returns a single record. All these actions are done using the GET verb, which as a side effect means they are also accessible via the browser.

You'll need to pass the API key by adding a header to the curl command. So, if your key was 123-456-789, your command would be..

curl -H 'API_KEY: 123-456-789' http://redeparede.com.br/sao-paulo/a-venda/autopecas/posts.xml

curl -H 'API_KEY: 123-456-789' http://redeparede.com.br/sao-paulo/a-venda/autopecas/posts/bloqueador-de-veiculos-sem-mensalidade-79284.xml

If the read is successful, you'll receive a "200 OK" HTTP response back.

Writing through the API

Creating, updating, and deleting resources through the API is almost as easy as reading, but it can't be explored it as easily using a browser. However to explore the API, or to create small scripts, curl is a great tool.

When creating or updating resources, you need to send the data as XML. To let the system know that you are sending XML, you need add the header "Content-type: application/xml". Then just include the XML in the body of your request.

For example - creating a post using curl:

curl -u username:password -H 'Content-Type: application/xml' \
-d "<post><title>My Great New Product</title><body>This is Textile enabled body text. </body><category-id type="integer">9</category-id><city-id
type="integer">33</city-id><duration type="integer">1</duration></post>" http://redeparede.com.br/posts.xml

The response to a succesful creation is the status code "201 Created". You can get the URL of the new resource in the Location header (so that you know where to update your new resource in the future).

Updating resources is done through the PUT verb and against the URL of the resource you want to update.

curl -u username:password -H 'Content-Type: application/xml' \
-d "<post><title>My Great New Product</title><body>Brand NEW body text. </body><category-id type="integer">9</category-id><city-id
type="integer">33</city-id><duration type="integer">1</duration></post>" http://redeparede.com.br/posts/my-great-new-product-1.xml

The response to a successful update is "200 OK".

Dealing with failure

There are a number of error codes you could see when dealing with the API.

If the resource you were trying to find could not be found then we will return a "404 Not Found" error code.

If the username / password combination were incorrect, then you be issued with a "401 Unauthorized" error.

If the record sent via XML is incorrect, you will receive a "422 Unprocessable Entity" error message with details of the error encoded in XML.

Conventions in the API documentation

In the documentation that follows, the following notation is used:

#{text} : This text that should be replaced by your own data
... : Additional content from the response has been removed for brevity in documentation.

Cities

List All

GET /cities.xml

Returns a list of cities for the country. In the form:

Response


Status: 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<cities type="array">
  <city>
    <id type="integer">45</id>
    <name>Sao Paulo</name>
    <permalink>sao-paulo</permalink>
  </city>
  ...
</cities>

Posts

List All

Filtered List - Paginated

GET /posts.xml

Returns a list of all posts, restricted to certain conditions, and ordered depending on conditions.

Params:

category_id: The top_level_category permalink of the required top level category.
sub_category_id: The permalink of the required category.
city_id: The permalink of a city.
user_id: The login of a user.
tag_name: The name of a tag
order: Specify the order in which the posts should be returned. See ordering.
page: 15 posts are returned with each request. If no page parameter is given then it defaults to 1, thus returning the first 15 posts that are returned by the search. To get the next 15 posts set page=2, then the next 15 set page=3 and so on.

NOTE: The category_id and sub_category_id should be used independently of each other.

Ordering:

created_at: Order the posts from earliest to latest.
created_at-desc: Order the posts from latest to earliest.
price: Order the posts from cheapest to most expensive.
price-desc: Order the posts from most expensive to cheapest.
popularity: Order the posts from least popular to most popular.
popularity-desc: Order the posts from most popular to least popular.

NOTE: As the prices can contain additional information, such as "per week", the posts may not be strictly sorted in most expensive to cheapest.

Response


Status: 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<records type="array">
  <record>
    <id type="integer">1</id>
    <title>My Great Product</title>
    <permalink>my-great-product-8</permalink>
    <body-html>&lt;p&gt;This is my great new product, available to you for a small price.&lt;/p&gt;</body-html>
    <contact-telephone>01234567890</contact-telephone>
    <popularity type="integer">400</popularity>
    <created-at type="datetime">2008-01-01T13:08:54+00:00</created-at>
    <preview type="boolean">false</preview>
    <tags type="array">
      <tag>
        <id type="integer">1</id>
        <name>Sample</name>
      </tag>
    </tags>
  </record>
</records>

Show

GET /posts/#{permalink}.xml

Response


Status: 200 OK

List Expired

GET /users/#{user_permalink}/posts/expired.xml

Response


Status: 200 OK

Create

POST /posts.xml

Request


<?xml version="1.0" encoding="UTF-8"?>
<post>
  <title>My Great New Product</title>
  <body>
    This is Textile enabled body text.

    So the user can create paragraphs like this.
  </body>
  <category-id type="integer">9</category-id>
  <city-id type="integer">33</city-id>
  <duration type="integer">1</duration>
  ...
  <location-tags>comma, seperated, keywords</location-tags>
  <keyword-tags>comma, separated, tags</keyword-tags>
  <contact-telephone>0123456789</contact-telephone>
  <upload1></upload1>
  <upload2></upload2>
  <upload3></upload3>
</post>

Response


Status: 201 Created
Location: http://redeparede.com.br/#{city_permalink}/#{category_permalink}/#{sub_category_permalink}/#{post_permalink}.xml

<?xml version="1.0" encoding="UTF-8"?>
<post>
  ...
</post>

Update

PUT /posts/#{permalink}.xml

Request


<?xml version="1.0" encoding="UTF-8"?>
<post>
  ...
</post>

Response


Status: 200 OK

Users

List All Paginated

List By Login, Email or Name

GET /users.xml

Params:

terms: A search term to filter users by.
scope: Which field to find the given terms in. See scoping
page: 10 users are returned with each request. If no page parameter is given then it defaults to 1, thus returning the first 10 users that are returned by the search. To get the next 10 posts set page=2, then the next 10 set page=3 and so on.

Scoping:

members: Find users where the login, email or name includes the terms provided.
login: Find users where the login includes the terms provided.
email: Find users where the email includes the terms provided.
name: Find users where the name includes the terms provided.

Request


Status: 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<users type="array">
  <user>
    <id type="integer">1</id>
    <real-name>Quentin Pilpot</real-name>
    <login>quentin</login>
    <website>http://www.moo.com/</website>
    <avatar-url>/missing_avatar/avatar.gif</avatar-url>
    <about-me>Hi, I am Quentin. 

  I am the RedeParede Crash Dummy.</about-me>
    <city>
      <id type="integer">11</id>
      <name>Brasilia</name>
      <permalink>brasilia</permalink>
    </city>
    <created-at type="datetime">2007-12-28T13:09:55+00:00</created-at>
  </user>
  ...
</users>

Show

GET /users/#{permalink}.xml

Returns an existing user.

Response


Status: 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <id type="integer">1</id>
  <real-name>Quentin Pilpot</real-name>
  <login>quentin</login>
  <website>http://www.moo.com/</website>
  <avatar-url>/missing_avatar/avatar.gif</avatar-url>
  <about-me>Hi, I am Quentin. 

I am the RedeParede Crash Dummy.</about-me>
  <city>
    <id type="integer">11</id>
    <name>Brasilia</name>
    <permalink>brasilia</permalink>
  </city>
  <created-at type="datetime">2007-12-28T13:09:55+00:00</created-at>
</user>

Create

POST /users.xml

Request


<?xml version="1.0" encoding="UTF-8"?>
<user>
  <login>joe</login>
  <password></password>
  <password-confirmation></password-confirmation>
  <email></email>
  <email-confirmation></email-confirmation>
  <city-id></city-id>
  <captcha-code></captcha-code>
  <captcha></captcha>
  ...
  <real-name></real-name>
</user>

Response


Status: 201 Created
Location: http://redeparede.com.br/users/#{permalink}.xml

<?xml version="1.0" encoding="UTF-8"?>
<user>
  ...
</user>

Update

PUT /users/#{permalink}.xml

Request


<?xml version="1.0" encoding="UTF-8"?>
<user>
  ...
</user>

Response


Status: 200 OK

Entrar ou cadastrar-se

API documentation

Introduction

Authentication

Reading through the API

Writing through the API

Dealing with failure

Conventions in the API documentation

Categories

List All

GET /categories.xml

Response

Cities

List All

GET /cities.xml

Response

Posts

List All

Filtered List - Paginated

GET /posts.xml

Params:

Ordering:

Response

Show

GET /posts/#{permalink}.xml

Response

List Expired

GET /users/#{user_permalink}/posts/expired.xml

Response

Create

POST /posts.xml

Request

Response

Update

PUT /posts/#{permalink}.xml

Request

Response

Tags

List Popular

GET /tags.xml

Response

Users

List All Paginated

List By Login, Email or Name

GET /users.xml

Params:

Scoping:

Request

Show

GET /users/#{permalink}.xml

Response

Create

POST /users.xml

Request

Response

Update

PUT /users/#{permalink}.xml

Request

Response

No Mundo