apis rest #devfestbilbao

#REST

Asier Marqués

@asiermarques

linkedin.com/in/asier @asiermarques

HTTP

HTTP - RFC 2616

Request Response

Request

GET /usuarios Accept: text/html, application/json

Response

GET /usuarios Status Code: 200 Content Type: application/json

¿Por qué hacer APIs HTTP?

Evitar la dependencia del cliente con el backend.

Utilizar un protocolo maduro, probado y muy usado.

Mejorar la integración con servicios o

aplicaciones de terceros.

RESTFul

Richardson Madurity Model

Nivel 1 – Uso correcto de las URIs

Nivel 2 – Uso correcto de HTTP

Nivel 3 – Hypermedia

Nivel 1 - URIs

Recursos y URIs

Cada información con la que queramos trabajar es un recurso. Usamos URLs, un tipo de URI que identifica y localiza un recurso.

Recursos

Un listado de usuarios → /usuarios

Un usuario → /usuarios/{id}

Nombrar recursos

Usamos nombres, no verbos

Utilizamos una estructura jerárquica

Evitamos añadir: Nombres de formatos Extensiones Filtros, órdenes paginaciones

Incorrecto

Perfil de usuario → /getUser/{id}

Edición de usuario → /users/{id}/edit

Paginación de listado → /users/page/{page}

Relaciones → /invoices/user/{id}

Incorrecto

Perfil de usuario → /getUser/{id}

Edición de usuario → /users/{id}/edit

Paginación de listado → /users/page/{page}

Relaciones → /invoices/user/{id}

Correcto

Perfil de usuario → /users/{id}

Edición de usuario → /users/{id}

Paginación de listado → /users?page={page}

Relaciones → /user/{id}/invoices

Contenidos parciales, filtrados parciales

GET /usuario/{id}?campos=id,nombre,email

Status Code: 206

Formatos

Incorrecto

GET /user/{id}.xml

Accept: text/html

Correcto

GET /user/{id}

Accept: application/xml

Nivel 2 - HTTP

Métodos HTTP

Leer → GET

Crear → POST

Editar → PUT Editar parcialmente → PATCH

Eliminar → DELETE Opciones disponibles → OPTIONS

Códigos de estado HTTP

No reinventar la rueda

RFC 2616 – Sección 10

Información → 1XX

Éxito → 2XX Redirección, proxy o caché → 3XX

Error de cliente → 4XX Error de servidor → 5XX

Tipo de contenido, media types HTTP

Request

GET /recurso Accept: application/json

Response

GET /recurso

Status Code 200

Content Type: application/json

Nivel 3 - Hypermedia

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

HATEOAS

Hypermedia as the Engine of Application State

RSDL

REST Service Description Language

GET pedido/{id}

<pedido> <id>666</id> <estado>Procesado</estado> <links>

<link rel=”factura”> http://api.acme.com/api/pedido/666/factura

</link> <link rel=”pago”>

http://api.acme.com/api/pedido/666/pago </link>

</links> </pedido>

Hypermedia y HATEOAS

Nos permite desacoplar al máximo el cliente del

servidor.

Nos da flexibilidad ante cambios futuros en

nuestra API.

Nos permite automatizar peticiones sin tener que

conocer de antemano la API.

Utilizamos media type propios.

Accept: application/vnd.{tu servicio} +json

GET /pedido/{id}

Request

Accept: application/vnd.acme+xml, application/xml

Response

Content Type:

application/vnd.acme+xml

HAL - Hypertext Application Language

application/hal+json

http://stateless.co/hal_specification.html

https://github.com/mikekelly/hal-browser

GET /users/john {

"username": "john", "bio": "Un tipo majísimo, siempre saluda en la escalera.", "real_name": "John Smith”, "_embedded": { "rs:addresses": [] },

"_links": { "self": { "href": "/users/john” },

"curies": [{ "name": "rs", "href": "http://api.acme.com/docs/rels/{rel}", "templated": true

}], "rs:posts": { "href": "/users/john/posts“ }, "rs:follow”: { "href": "/users/john“ }

} }

GET /users/john {

"username": "john", "bio": "Un tipo majísimo, siempre saluda en la escalera.", "real_name": "John Smith”, "_embedded": { "rs:addresses": [] },

"_links": { "self": { "href": "/users/john” },

"curies": [{ "name": "rs", "href": "http://api.acme.com/docs/rels/{rel}", "templated": true

}], "rs:posts": { "href": "/users/john/posts“ }, "rs:follow”: { "href": "/users/john“ }

} }

Más cosas

Versiones

En la URI

/api/v1/recurso

En el content-type

application/vnd.acme+json;v=1

application/vnd.acme-1+json

Seguridad

Autenticación HTTP: Basic, Digest

Sistema propio basado en tokens

OAuth

Gateways: Layer7, apigee enterprise, 3scale...

+ HTTPs (no es opcional)

Operaciones asíncronas

Callback URLs

Notificaciones PUSH

Inbound email parsing

Disponibilidad de formatos

Request

GET /recurso

Accept: application/xml

Response (formato disponible)

GET /recurso Content Type: application/xml

200

Response (formato no disponible) GET /recurso

406 Not acceptable

Uso de Etiquetas HTTP

Request

PUT /recurso

If-Match: “XXXX”

Response

PUT /recurso

200

Etag: “YYYY”

Request

PUT /recurso

If-Match: “XXXX”

Response

PUT /recurso

412 Precondition Failed

Etag: “YYYY”

Descripción de errores

Request

POST /users

Response

POST /users

201 Created

Request

POST /users

Response

POST /users

400 Conflict

Content

{

“_errors”: [{

“email”: “email is in use”

}]

}

Utilizando OPTIONS

Request OPTIONS /users

Response 200

Allow: GET, POST Content: { "POST": { "description": “Creamos un usuario",

"parameters": {} }, “GET”: { "description": “Recuperamos el listado de usuarios“ }

}

BaaS

Backend as a service

Disponemos de una API de servidor totalmente

funcional en minutos.

Sin problemáticas de infraestructura,

administración de servidores..

Integración con servicios de terceros out of the

box, en algunos casos.

Personalización del código de la API mediante Javascript y Eventos.

BAAS, Backend as a Service

Gracias

@asiermarques