Design considerations

JSON format

Is an open standard based on lightweight text designed for the exchange of readable data. You can read these types of messages through a browser, specific tools (Ex: Postman) or from any development that consumes the Mercado Libre API. For a JSONP response, add a callback parameter as follows:

Example:

curl -X GET https://api.mercadolibre.com/currencies/MXN?callback=foo

Response:

foo([
    200,
    {
        "Cache-Control": [
            "max-age=3600,stale-while-revalidate=1800, stale-if-error=7200"
        ],
        "Content-Type": [
            "text/javascript;charset=UTF-8"
        ]
    },
    {
        "id": "MXN",
        "symbol": "$",
        "description": "Peso Mexicano",
        "decimal_places": 2
    }
]);

As you can see, the response is an array with 3 values:

• HTTPS status code
• HTTPS response headers
• Body of the response

All JSONP responses will always be 200 OK. This is in order to give you the chance to handle 30x, 40x, and 50x responses on the client side. The real response data is in the array.

Error format

The standard format of an error is as follows:

{
  "message": "human readable text",
  "error": "machine_readable_error_code",
  "status": 400,
  "cause": [ ],
}

Reduce responses

To have shorter answers, with less data, you can add the attributes parameter with a comma by separating the list of fields that should be included in the response.

curl -X GET https://api.mercadolibre.com/currencies?attributes=id

Response:

[
    {
        "id": "ARS"
    },
    {
        "id": "BOB"
    },
    {
        "id": "BRL"
    },
    {
        "id": "CLF"
    },
    {
        "id": "CLP"
    },
    {
        "id": "COP"
    },
    {
        "id": "CRC"
    },
    {
        "id": "CUC"
    },
    {
        "id": "CUP"
    },
    {
        "id": "DOP"
    },
    {
        "id": "EUR"
    },
    {
        "id": "GTQ"
    },
    {
        "id": "HNL"
    },
    {
        "id": "MXN"
    },
    {
        "id": "NIO"
    },
    {
        "id": "PAB"
    },
    {
        "id": "PEN"
    },
    {
        "id": "PYG"
    },
    {
        "id": "USD"
    },
    {
        "id": "UYU"
    },
    {
        "id": "VEF"
    },
    {
        "id": "VES"
    }
]

Results pagination

You can define the page size of the result list. There are 2 parameters: limit and offset. Both parameters define the size block of the results. This article is based on the search example, but you can use pagination on each resource that is presented in the "pagination" response information, as shown below:

"paging": {
  "total": 285,
  "offset": 0,
  "limit": 50,
  }

Default values

The default values depend on the API, generally the most common are offset=0 and limit=50. In the pagination section of the JSON response, you can see the total number of articles matching the search and the offset value with the default limit applied.
Limit: use it to reduce the page size, you can change the limit parameter. For example, if you are interested in recovering only the first 3 items.
Offset: By using the offset attribute, you can move the lower limit of the result block. For example, if you are interested in recovering the 50 articles that follow the default response.
Define a range of results: It is possible to combine both parameters. You can retrieve items from the third to the sixth in the original search result: offset=3&limit=3

Next: Best practices for listing items.