Consideraciones de diseño

Existen algunos temas que debes saber sobre nuestra API para facilitarte la vida.

Contenidos:

Todas las respuestas están codificadas con JSON

JSON es un estándar abierto basado en texto ligero diseñado para el intercambio de datos legibles por humanos. Nuestra API soporta y devuelve JSON por defecto.
También devolvemos respuestas HTML cuando estás navegando la API a través de un navegador web.
Para decidir qué respuesta devolvemos, utilizamos el encabezado Accept. Para superar la política del mismo origen, JSONP también está soportado.
La política del mismo origen es un concepto de seguridad importante. Para superarla, sugerimos utilizar JSONP y CORS.

Uso de JSONP

Si incluyes un parámetro callback, la API responderá con JSONP. El valor de este parámetro se utilizará como la función de callback.

Ejemplo:

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

Respuesta:

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

Para una respuesta JSONP, agrega un parámetro callback como éste:

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

Respuesta:

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 puedes ver, la respuesta es un conjunto de 3 valores:

  • Código de estado http
  • Encabezados de respuesta http
  • Cuerpo de la respuesta

Todas las respuestas JSONP siempre serán 200 OK. El propósito es darte la posibilidad de manejar respuestas 30x, 40x y 50x en el client side. Los datos reales de la respuesta están en el conjunto.

CORS

Cross-origin resource sharing (CORS) [compartir recursos de origen cruzado] es una especificación tecnológica del navegador web que define formas en las cuales un servidor web permite el acceso a sus recursos a través de una página web de un dominio diferente. Ésta es una manera de superar la política del mismo origen.
Todas las API devuelven un encabezado especial:

Access-Control-Allow-Origin: *

Esto permite al buscador acceder a la información provista por la API, aunque sea desde un dominio diferente.
Todos los principales navegadores cuentan con soporte para CORS.
Entonces, básicamente, esto significa que no tienes que hacer nada y puedes acceder a la API directamente desde tu navegador realizando llamadas ajax normales con todos los métodos estándares y evitando cosas como JSONP.

Todas las solicitudes/respuestas están codificadas con UTF-8

User: Are you really telling me that I can only use UTF-8 with MELI APIs?
Us: Yes.
User: Really?
Us: Yes.
User: Only?
Us: Yes. We hope this has been enlightening for you.
User: But, I must–
Us: Thank you, come again.
User: But–
Us: Thank you, come again.

Todas las fechas están codificadas con ISO 8601

Utilizamos ISO 8601 para codificar las fechas en las respuestas.
No todas las fechas utilizarán el mismo huso horario. Por eso, las fechas incluirán el huso horario correcto.

Manejo de errores

El formato estándar de un error es el siguiente:

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

Reducción de respuestas

Para contar con respuestas más breves, con menos datos, puedes agregar el parámetro atributos con una coma separando la lista de campos que se deberían incluir en la respuesta. Todos los demás campos de la respuesta original se ignorarán.
Esta característica solo está soportada para el conjunto de respuestas.

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

Esta característica solo está soportada para el conjunto de respuestas
Filtra por ID de recursos
Si tienes una lista de los ID de los recursos que deseas recuperar, puedes evitar realizar N cantidad de llamadas para obtenerlos y hacerlo con una sola llamada. Esto se logra al agregar el parámetro ID a la cadena de consulta.

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

Uso de OPCIONES

La API entregará documentación en formato JSON utilizando OPTIONS. Existe un formato estándar para obtener documentación de la API. Utiliza el método http OPTIONS para obtener una respuesta codificada con JSON que describirá la API con todos los métodos y conexiones permitidos entre otra parte de la 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"
	}
}



Siguiente:
Registra tu aplicación.

Por favor califica del 1 al 5