Un repaso al tutorial RESTful
Las siglas REST significan: REpresentational State Transfer
Interface uniforme tiene cuatro principios guía:
El estado está dentro del request.
No hay sesion client -> server -> cliente
Potencia la escalabilidad. Cada petición es una nueva petición.
Manipulación de estado de un recurso:
Los clientes pueden cachear respuestas.
Las respuestas deben definir de manera implicita o explicita si son cacheables o no, para reusar o no sus datos en futuras peticiones.
Bien manejado, este mecanismo elimina algunas interacciones entre cliente-servidor, mejora escalabilidad e incrementa el performance.
El servidor puede transferir comportamiento (lógica) al cliente para que este último lo ejecute.
Es la única restricción opcional. Es decir, un servicio web puede denominarse RESTful si cumple todas las restricciones o todas menos esta.
Los clientes de las APIs usan los verbos HTTP para las operaciones que representan:
La operación GET no debe cambiar el estado del recurso. Tras un GET el recurso sigue siendo el mismo.
Construir un API es 80% arte y 20% ciencia.
La parte artística es crear una jerarquía URL que represente recursos sensibles.
Ejemplos:
/customer -> todos los clientes
/customer/123 -> cliente 123
/customer/123/orders -> ordenes de cliente 123
/customer/123/orders/45 -> orden 45 de cliente 123
/customer/123/orders/45/products -> productos en orden 45 de cliente 123
/customer/123/ordes/45/products/67 -> producto 67 de orden 45 de cliente 123
Usa identificadores en la URL en lugar de en el query-string:
Nombra los recursos en su orden natural
Diseña para los clientes, no para tus datos
Nombres de recursos como sustantivos, no como verbos. La acción la define el HTTP Verb
Utiliza plurales en los nombres de recursos
Si se trata de colecciones:
Utiliza lower-case en segmentos, separando palabras con "-"
URIs cortas, tanto como sea posible, no restando significado
Son un estándar.
Existe uno para casi todas las situaciones.
Usar los relevantes en cada situación.
Ejemplo:
Create resource -> 201 CREATED
JSON
{ "montoCredito": 200000.00, "comisionAnual": 1100, "tasaInteresAnual": 35, "pagoMinimo": 10 }
XML
<?xml version="1.0" encoding="UTF-8" ?>
<montoCredito>200000</montoCredito>
<comisionAnual>1100</comisionAnual>
<tasaInteresAnual>35</tasaInteresAnual>
<pagoMinimo>10</pagoMinimo>
Los más usados:
Se corresponden con las operaciones CRUD sobre los recursos.
Otros verbos no tan utilizados con REST
| Verbo HTTP | Operación CRUD | Response Code |
|---|---|---|
| POST | Create | 201 Created, 404, 409 |
| GET | Read | 200 OK, 404 |
| PUT | Update/Replace | 200, 204, 404 |
| DELETE | Delete | 200, 404 |
Ejemplos POST:
Ejemplos:
Ejemplos:
Ejemplos:
Es de los temas más debatidos a la hora de diseñar APIs
Una RESTful API es una combinación de una colección de URIs (recursos) y operaciones sobre esas URIs (verbos HTTP), más el uso de buenas prácticas y convenciones.
Ejemplos de recursos:
Cada recurso en el API tiene al menos una URI que lo identifica.
Es mejor si la URI tiene sentido y describe al recurso.
Se presentan ejemplos de nombrado correcto de recursos para un API que expone clientes, ordenes de compra, linea de productos y productos.
Para insertar (crear) un nuevo cliente en el sistema, deberíamos usar:
Para consultar un cliente el ID# 33245:
La misma URI debería ser usada para PUT y DELETE.
Aqui una URI propuesta para crear un producto:
Cómo relacionar un recurso OrdenDeCompra y cliente?
Primer intento:
Crea la orden? Sí, pero el problema es que esto no relaciona la orden con un cliente. La orden está fuera del contexto del cliente. Veamos un segundo intento:
Claramente se entiende que estamos creando una orden de compra para el cliente con ID#33245
Una jerarquía más profunda sería:
Así no se deben nombrar recursos.
Usar query-parameter para indicar la operacion y el verbo HTTP.
GET http://api.example.com/services?op=update_customer&id=12345&format=json
"Services" es sustantivo, pero no autodescriptivo.
Usa GET para un UPDATE. :O
Problemático (incluso peligroso) para el cliente.
Igual de peligroso es:
GET http://api.example.com/update_customer/12345
GET http://api.example.com/customers/12345/update
PUT http://api.example.com/customers/12345/update