We have seen in first chapter how to setup the application, in this chapter we will see how to manage adverts.
Retrieve Adverts
URL to call:
GET http://afariat.com/api/v1/adverts.{_format}?apikey=My_API_KEY{¶meter1=param1¶meter2=param2}
By default you will get a 20 adverts, when you call this url.
The _format can be json or xml. By default it is set to json.
You can make filters to retrieve adverts list. So to filter result, just add some parameters. in the next section, a description of available parameters.
Filters
| Parameter | Requirements | Is nullable | Description | Default |
|---|---|---|---|---|
| categoryGroup | Integer | YES | The catgory group to filter on | – |
| category | Integer | YES | The catgory to filter on. it will be ignored if categoryGroup was set. | – |
| advertType | Integer | YES | restrict results on this advertType | 1 |
| city | Integer | YES | restrict results to this city | – |
| town | Integer | YES | restrict results to this town | – |
| search | string | YES | The text to search | – |
| page | Integer | YES | Page of the overview. | 1 |
| limit | Integer | YES | Adverts count limit. For future use | 20 |
| sort | (a.price|a.modifiedAt)+ | YES | Sort parameter. | a.modifiedAt |
| direction | (asc|desc)+ | YES | Sort direction | desc |
Example of use
- Get Vehicles in Tunis city sorted by date of update in descendant order
GET http://afariat.com/api/v1/adverts?apikey=baee7c75e3d1f5ca5f93cc2e7ec1d771ffb285d2190b9f77db77fff21b93d283&city=23&sort=a.modifiedAt&direction=desc
- Get apartments for vacation rentals in Nasr I Town
GET http://afariat.com/api/v1/adverts?apikey=baee7c75e3d1f5ca5f93cc2e7ec1d771ffb285d2190b9f77db77fff21b93d283&town=8
Response
The response,by default is Json. You can use any JSON client to parse it.
The response looks like this:
{
"page": 1,
"limit": 20,
"pages": 58,
"total": 1159,
"_links": {
"self": {
"href": "/api/v1/adverts?sort=a.modifiedAt&direction=desc&advertType=1&page=1&limit=20"
},
"first": {
"href": "/api/v1/adverts?sort=a.modifiedAt&direction=desc&advertType=1&page=1&limit=20"
},
"last": {
"href": "/api/v1/adverts?sort=a.modifiedAt&direction=desc&advertType=1&page=58&limit=20"
},
"next": {
"href": "/api/v1/adverts?sort=a.modifiedAt&direction=desc&advertType=1&page=2&limit=20"
}
},
"_embedded": {
"adverts": [
{
"id": 2276,
"categoryGroup": {
"id": 3,
"name": "Vêtements et objets personnels",
"_links": {
"list": {
"href": "/api/v1/adverts?categoryGroup=3"
}
}
},
"photo": "uploads/adverts/ce11f8d29451f02b5d836cd43ca4f3a5bde65162.jpg",
"description": "Montre AUGUST Steiner presque neuf modèle 2014\r\nPrix:100dt",
"title": "Montre AUGUST steiner",
"price": 100,
"city": {
"id": 13,
"name": "Manouba",
"_links": {
"list": {
"href": "/api/v1/adverts?city=13"
}
}
},
"modified_at": "2015-06-03T11:54:40+0100",
"_links": {
"self": {
"href": "/api/v1/adverts/2276"
}
}
}
]
}
}
Description
As result, you have two informations:
-
Metadata
page: what page you are browsing
limit: the limit of the rsults
pages: The total number of pages found that matches your query
The special _links:
It shows you the links of the paginator. Using this links, you can browse results without building a new query for the same criterias.
-
- self: The URL of current page result
- first: The URL of the first page result
- last: The URL of The last pasge
- next: The URL of the next page.
- Data
Data in “adverts” collection under “_embedded” section. It’s a normal Json content, so you can parse it using any Json Client.
There is a special key under “_links” of categoryGroup and city keys which is “list“.
"_links": {
"list": {
"href": "/api/v1/adverts?city=13"
}
}
It shows you that you can get all adverts in that categoryGroup using that URL (e.g: )
Response codes:
| Code | Description |
|---|---|
| 200 | OK |
| 401 | Unauthorized. If no apikey was given |
| 403 | Forbidden. Given apikey not exists or it was disbled |
| 500 | Server Error |
Questions ?
If you have any question, please post it in the dedicated Forum Secion.
Previous: Chapter 1: Introduction & setup