API REST 101:
Consejos y aclaraciones sobre REST API
¿Qué veremos?
- ¿Qué es una API?
- ¿Qué es REST API?
- ¿Cuándo usar REST API?
- Buenas prácticas
- Y... ¿GraphQL?
¿Qué es una API?
API != IPA
Application
Programing
Interface
Conjunto de subrutinas, funciones (o métodos) y procedimientos que ofrece una biblioteca para que otro software los utilice mediante una capa de abstracción
¿Qué es REST API?
Estilo de arquitectura de software para sistemas distribuidos que describe interfaces de comunicación mediante el protocolo HTTP
La base de comunicación de una API REST son las URL
¿Cuándo usar REST API?
Ahora si...
Buenas prácticas
(consejos a seguir)
Abstracto
vs
Concreto
Perros y Gatos, no Animales
Limones y Peras, no Frutas
CRUD como verbos HTTP
Operación CRUD
- Create
- Read
- Update
- Delete
Verbo HTTP
- POST
- GET
- PUT
- DELETE
Recurso | GET | POST | PUT | DELETE |
---|---|---|---|---|
/movies | Listar todas las películas | Crear una nueva película | Reemplaza el listado de todas las películas por un nuevo listado | Elimina todas las películas |
/movies/1 | Obtiene los datos de la película 1 | ERROR | Reemplaza la película 1 en caso de existir, en caso contrario ERROR | Elimina la película 1 |
Estructurar las URL
{protocol}://{domain}:[port]/{collection}/api/{version}/{resource}
http://localhost:8080/cinema/api/v1/movies https://localhost:8080/cinema/api/v1/movies/1
IMPORTANTE
usar sustantivos y evitar verbos
(en lo posible)
HATEOAS
(wtf?!)
Hypermedia As The Engine Of Application State
{
"movieId": 1,
"name": "Avengers: Infinity War",
"year": "2018",
"links": [
{
"rel": "self",
"url": "http://localhost:8080/cinema/api/v1/movies/1"
},
{
"rel": "cast",
"url": "http://localhost:8080/cinema/api/v1/movies/1/cast"
}
]
}
Manejo de Errores
Ejemplo de un error en formato JSON
{
"status": 204,
"errorCode": 52,
"errorMessage": "No existen películas en el sistema",
"errorData": {
"httpVerb": "PUT",
"requestedUrl": "http://localhost:8080/cinema/api/v1/movies",
"requestedParams": {}
},
"errorTimestamp": "2018-03-30 12:43:30"
}
Seguridad
Es MUY IMPORTANTE proteger las modificaciones de los recursos
Una táctica recomendada es solicitar headers de autenticación en los puntos que exponemos en nuestra API.
Idealmente estos headers debieran tener información encriptada de el usuario que está haciendo la solicitud, para poder filtrar por:
- Autenticación: ¿es un cliente válido en el sistema o es un externo no identificado?
- Autorización: ¿es un cliente con permisos suficientes para acceder al recurso solicitado?
Versionamiento
En software, SIEMPRE versionar todo tipo de API
Filtrado y Paginación
Filtrado
{
"id": 42,
"name": "Robert John Downey Jr.",
"age": 52,
"height": 1.72,
"birthplace": "Manhattan, NY",
"nationality": "USA",
"movies": [...],
"children": [...],
"parents": [...]
}
{
"id": 42,
"name": "Robert John Downey Jr.",
"age": 52
}
/actors/42
/actors/42?id,name,age
Paginación
[
{"id": 1, ...},
{"id": 2, ...},
{"id": 3, ...},
{"id": 4, ...},
{"id": 5, ...},
{"id": 6, ...},
{"id": 7, ...},
{"id": 8, ...},
{"id": 9, ...},
{"id": 10, ...},
{"id": 11, ...},
{"id": 12, ...},
{"id": 13, ...},
{"id": 14, ...},
...
]
/actors
/actors?limit=10&offset=30
[
{"id": 31, ...},
{"id": 32, ...},
{"id": 33, ...},
{"id": 34, ...},
{"id": 35, ...},
{"id": 36, ...},
{"id": 37, ...},
{"id": 38, ...},
{"id": 39, ...},
{"id": 40, ...}
]
Documentación
El principio de la documentación es aclarar lo que uno ha hecho a un tercero.
El principio de una API es hacer público lo que uno ha hecho, para que lo usen terceros.
apidocjs: http://apidocjs.com/example/
swagger: http://petstore.swagger.io
Y... ¿GraphQL?
Viene a reemplazar las REST API
Pero esto no ocurrirá hasta por lo menos unos años más. Es una tecnología emergente, mientras que REST API es el estándar usado en la industria actualmente
De todas formas, si saben GraphQL esto sumará valor a su curriculum
¡Gracias por su atención!
API REST 101
By Pablo Ulloa Castro
API REST 101
- 507