¿Qué es una API?

Es el conjunto de subrutinas, funciones y procedimientos que ofrece cierta biblioteca para ser utilizado por otro software como una capa de abstracción.

¿Y una API REST?

API REST

Es un servicio que nos provee de funciones que nos dan la capacidad de hacer uso de un servicio web que no es nuestro.

¿Qué es REST?

Describe cualquier interfaz entre sistemas que utilice directamente HTTP para obtener datos o indicar la ejecución de operaciones sobre los datos, en cualquier formato (XML, JSON, etc)

Transferencia de Estado Representacional 

(REpresentational State Transfer)

Ejemplos

Twitter

Facebook

Stripe

¿Ventajas?

Ventajas

Separación entre el cliente y el servidor

Independencia de lenguaje

Escalabilidad al no tener estado

Buenas prácticas

Usa todos los métodos

• GET (obtener)
• POST (crear)
• PUT (actualizar)
• PATCH (actualizar)
• DELETE (eliminar)

Usa los códigos de estado HTTP

• 1xx - Respuestas informativas
• 2xx - Peticiones correctas
• 3xx - Redirecciones
• 4xx - Errores del cliente
• 5xx - Errores del servidor

Devuelve JSON

(jotasón)

URLs

Usa nombres, no verbos

Siempre en plural

Facilita la vida al consumidor aunque el nombre no coincida internamente

Ejemplos de URLs

GET /posts - Devuelve todos los artículos

GET /posts/1 - Devuelve el artículo con el ID 1

POST /posts - Crea un nuevo artículo

PUT /posts/1 - Actualiza el articulo con el ID 1

DELETE /posts/1 - Elimina el artículo con el ID 1

Ejemplos de URLs

GET /posts/1/comments

Devuelve todos los comentarios del artículo 1

POST /posts/1/comments

Crea un nuevo comentario en el artículo 1

PUT /posts/1/comments/5

Actualiza los datos del comentario 5 del art. 1

Orden, paginación, búsquedas...

Añade la posibilidad de ordenar los listados (ej. ?sort=-popular)

Pagina los resultados (ej. ?page=1&per_page=5)

Permite búsquedas: (ej. ?q=Laravel)

Relaciones

Permite insertar relaciones en las peticiones. Por ejemplo:

/users?with=posts

/posts/1?with=comments.user

Autenticación

sin estado

No se almacenan los usuarios en sesiones, ahorrando memoria

Devuelve errores

Pero hazlo bien

No es lo mismo devolver

que

{
  "status": "error"
}

{
  "status": "error",
  "message": "El email es obligatorio",
  "status_code": 422,
  "error_code": "validation_error"
}

Versiona tu API

Documenta tu API

Generadores de documentación

http://apidocjs.com/

http://swagger.io/

https://apiblueprint.org/

https://github.com/tripit/slate (como stripe)

No reinventes

Rest- Framework

Dingo/Api

Api Handler

Rails-Api

Clientes REST

POSTMAN (chrome app y extension)

PAW

REST CLIENT

¡Vamos al código!

¿Preguntas?

¡Beer time!