Diseño de un API RESTful

¿Qué es un API?

Application Program Interface

Una API es un conjunto de definiciones y protocolos que se utiliza para desarrollar e integrar distintas piezas de software.

¿Qué es un API REST?

REST, or REpresentational State Transfer, is an architectural style for providing standards between computer systems on the web, making it easier for systems to communicate with each other.

Es un estilo de arquitectura software, centrada en los recursos, que sirve para construir API sobre el protocolo HTTP.

HTTP y REST

HTTP utiliza determinados verbos: GET, POST, PUT, PATCH, DELETE, etc.
Los recursos se identifican con una URI
/preferencias
Verbo HTTP + URI = endpoint
GET /preferencias
Un endpoint representa una acción sobre un recurso
Existe una correspondencia entre verbos y CRUD

GET  /orders          <---> orders (colección)
POST /orders          <---> orders.push(data)
GET  /orders/1        <---> orders[1]
PUT  /orders/1        <---> orders[1] = data
GET  /orders/1/lines  <---> orders[1].lines
POST /orders/1/lines  <---> orders[1].lines.push(data)

Los recursos

Deben ser nombrados utilizando nombres
Las URI no deben contener acciones (verbos)

GET /crear_perfil
GET /getAllUsers
POST /perfil

Deben identificar a una entidad de negocio

Las respuestas

Nunca debe responderse con texto plano
Utilizar JSON y por lo tanto:
Content-Type: application/json
Los códigos de la respuesta importan:
- 1xx for information, 2xx for success
- 3xx for redirection, 4xx for client errors
- 5xx for server errors.

Ejemplo de respuesta

 HTTP/1.1 201 Created
Content-Type: application/json
 
{
    "order_id": "134234",
    "customer": {
        "client_id": 233231,
        "name": "Óscar",
        "surname": "García"
    },
    items:[ 1, 23, 123, 5, 52]

 HTTP/1.1 400 Bad Request
Content-Type: application/json
 
{
    "error": "Expected at least two items in list."
}

Colecciones: búsquedas, filtros, ordenación y paginación

Utiliza el campo query de la URI

GET /client?sort=last_purchase
GET /client?company=3&zone=28
GET /client?search=garcia
GET /client?page=23

A jugar!

Otros jugadores:

	HTTP/1.1 201 Created
	Content-Type: application/json

	{
	"order_id": "134234",
	"customer": {
	"client_id": 233231,
	"name": "Óscar",
	"surname": "García"
	},
	items:[ 1, 23, 123, 5, 52]

	HTTP/1.1 400 Bad Request
	Content-Type: application/json

	{
	"error": "Expected at least two items in list."
	}