Considerações sobre design

Para facilitar sua vida, há alguns itens que você deve saber sobre nossa API.

Assuntos

Todas as respostas são codificadas no formato JSON

JSON é um padrão aberto baseado em texto leve usado para a troca de dados legíveis por humanos. Por padrão nossa API aceita e entrega JSON.
Respostas HTML também são entregues quando você está navegando pela API usando um navegador da Web.
Para decidir qual resposta será enviada de volta, usamos o cabeçalho Accept.
Para superar a política de mesma origem, JSONP também é aceito.
A política de mesma origem é um importante conceito de segurança. Para dominá-la, sugerimos utilizar JSONP e CORS.

Uso do JSONP

Se você incluir um parâmetro de retorno, a API responderá em formato JSONP. O valor desse parâmetro será usado como função de retorno.

Exemplo:

 $ curl https://api.mercadolibre.com/currencies/ARS

Resposta:

 {
  "id": "ARS",
  "description": "Peso argentino",
  "symbol": "$",
  "decimal_places": 2,
}

Para uma resposta JSONP, adicione um parâmetro de retorno como o seguinte:

 $ curl https://api.mercadolibre.com/currencies/ARS?callback=foo

Resposta:

 foo(
    [
        200, 
        {
            "ETag":"2995de5a04da39af0a8677b1d02d1cdb",
            "Vary":"Accept,Accept-Encoding",
            "Content-Type":"application/json;charset=UTF-8",
            "Cache-Control":"max-age=86400"
        }, 
        {
            "id":"ARS",
            "description":"Peso argentino",
            "symbol":"$",
            "decimal_places":2
        }
    ]
);

Como vemos, a resposta é um conjunto de três valores:

  • Código de status http
  • Cabeçalhos de resposta http
  • Corpo da resposta

Todas as respostas JSONP sempre serão 200 OK. O propósito disso é que você tenha a possibilidade de lidar com respostas 30x, 40x e 50x no client. Os dados reais da resposta estão no conjunto.

CORS

Cross-origin resource sharing (CORS) [compartilhamento de recursos de origem cruzada] é uma especificação tecnológica do navegador da Web que define formas pelas quais um servidor da Web permite o acesso a seus recursos através de uma página da Web de um domínio diferente. É uma forma de superar a política de mesma origem.
Todas as API retornam um cabeçalho especial:

Access-Control-Allow-Origin: *

Isto permite que o navegador acesse as informações fornecidas pela API, mesmo sendo de um domínio diferente.
Todos os principais navegadores contam com suporte a CORS.
Portanto, basicamente, isto quer dizer que você não precisa fazer nada e pode acessar a API diretamente de seu navegador, fazendo chamadas ajax normais com todos os métodos padrão e evitando coisas como JSONP.

Todas as solicitações/respostas são codificadas no formato UTF-8

Usuário: Você está realmente me dizendo que eu posso usar UTF-8 com a API do Mercado Livre?
Nós: Sim.
Usuário: Sério?
Nós: Sim.
Usuário: Mesmo?
Nós: Sim. Esperamos que isso tenha sido esclarecedor para você.
Usuário: Mas, eu devo–
Nós: Obrigado, volte sempre.
Usuário: Mas…
Nós: Obrigado, volte sempre.

Todas as datas são codificadas no formato ISO 8601

Nós utilizamos ISO 8601 para codificar as datas nas respostas.
Nem todas as datas usarão o mesmo fuso horário. Por isso, as datas incluirão o fuso horário certo.

Todos os erros têm um formato padrão

O formato padrão de um erro é o seguinte:

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

Use a seleção para reduzir a quantidade de atributos retornados

Para ter respostas mais curtas, com uma quantidade menor de dados, você pode acrescentar o parâmetro atributos com uma vírgula separando a lista de campos que devem ser incluídos na resposta. Todos os campos restantes da resposta original serão ignorados.
Isso só é aceito para as respostas do conjunto.

$ curl https://api.mercadolibre.com/currencies?attributes=id
[
  {
    "id": "BRL"
  },
  {
    "id": "UYU"
  },
  {
    "id": "CLP"
  },
  ...
]

Filtragem por IDs de recursos

Caso você tenha uma lista dos IDs de recursos que quer recuperar, você pode evitar N chamadas para obtê-los fazendo uma só chamada. Isso pode ser feito agregando o parâmetro IDs à cadeia de caracteres de consulta.

$ curl https://api.mercadolibre.com/currencies?ids=ARS,USD

A API fornecerá a documentação no formato JSON utilizando OPTIONS
Existe um formato padrão para obter a documentação da API. Utilize o método http OPTIONS para obter uma resposta codificada em JSON que descreverá a API com todos os métodos e conexões permitidos entre a outra parte da API.

$ curl -X OPTIONS https://api.mercadolibre.com/currencies
{
    "name":"Monedas",
    "description":"Devuelve información correspondiente al ISO de las monedas que se usan en MercadoLibre.",
    "attributes": {
        "id":"ID de la moneda (Código ISO)",
        "description":"Denominación oficial de la moneda",
        "symbol":"Símbolo ISO para representar la moneda",
        "decimal_places":"Número de decimales manejados con la moneda"
    },
    "methods": [
        {
            "method":"GET",
            "example":"/currencies/",
            "description":"Devuelve el listado con todas las monedas."
        },
        {
            "method":"GET",
            "example":"/currencies/:id",
            "description":"Devuelve información con respecto a una moneda específica."
        }
    ],
    "related_resources":[],
    "connections": {
        "id":"/currencies/:id"
    }
}



Próximo:
Registro de seu aplicativo.

Please rate this