Las APIs REST permiten desarrollar cualquier tipo de aplicación web con todas las operaciones CRUD (crear, recuperar, actualizar, eliminar) posibles. Las directrices de REST sugieren el uso de un método HTTP específico en un tipo particular de llamada hecha al servidor (aunque técnicamente es posible violar esta directriz, sin embargo, es altamente desaconsejado).
Use la información dada a continuación para encontrar un método HTTP adecuado para la acción realizada por la API.
Table of ContentsHTTP GETHTTP POSTHTTP PUTHTTP DELETEHTTP PATCHSummaryGlossary
HTTP GET
Use las peticiones GET para recuperar la representación/información de los recursos solamente – y no para modificarla de ninguna manera. Como las peticiones GET no cambian el estado del recurso, se dice que son métodos seguros. Además, las APIs GET deben ser idempotentes, lo que significa que hacer múltiples peticiones idénticas debe producir el mismo resultado cada vez hasta que otra API (POST o PUT) haya cambiado el estado del recurso en el servidor.
Si el Request-URI se refiere a un proceso que produce datos, son los datos producidos los que se devolverán como entidad en la respuesta y no el texto fuente del proceso, a menos que ese texto resulte ser la salida del proceso.
Para cualquier API HTTP GET, si el recurso se encuentra en el servidor, entonces debe devolver el código de respuesta HTTP 200 (OK) – junto con el cuerpo de la respuesta, que suele ser contenido XML o JSON (debido a su naturaleza independiente de la plataforma).
En caso de que el recurso NO se encuentre en el servidor, entonces debe devolver el código de respuesta HTTP 404 (NOT FOUND). Del mismo modo, si se determina que la propia petición GET no está correctamente formada entonces el servidor devolverá el código de respuesta HTTP 400 (BAD REQUEST).
Ejemplo de URIs de petición
- HTTP GET http://www.appdomain.com/users
- HTTP GET http://www.appdomain.com/users?size=20&page=5
- HTTP GET http://www.appdomain.com/users/123
- HTTP GET http://www.appdomain.com/users/123/dirección
HTTP POST
Usa las APIs POST para crear nuevos recursos subordinados, por ejemplo, un archivo está subordinado a un directorio que lo contiene o una fila está subordinada a una tabla de base de datos. Cuando se habla estrictamente en términos de REST, los métodos POST se utilizan para crear un nuevo recurso en la colección de recursos.
En realidad, si se ha creado un recurso en el servidor de origen, la respuesta DEBERÍA ser de código de respuesta HTTP 201 (Created) y contener una entidad que describa el estado de la solicitud y haga referencia al nuevo recurso, así como una cabecera Location.
Muchas veces, la acción realizada por el método POST podría no resultar en un recurso que pueda ser identificado por un URI. En este caso, el código de respuesta HTTP 200 (OK) o 204 (No Content) es el estado de respuesta apropiado.
Las respuestas a este método no son almacenables en caché, a menos que la respuesta incluya los campos de cabecera Cache-Control o Expires apropiados.
Tenga en cuenta que POST no es seguro ni idempotente, y la invocación de dos peticiones POST idénticas dará lugar a dos recursos diferentes que contengan la misma información (excepto los ids de recursos).
Ejemplo de solicitud URIs
- HTTP POST http://www.appdomain.com/users
- HTTP POST http://www.appdomain.com/users/123/accounts
HTTP PUT
Utilice las APIs PUT principalmente para actualizar un recurso existente (si el recurso no existe, entonces la API puede decidir crear un nuevo recurso o no). Si un nuevo recurso ha sido creado por la API PUT, el servidor de origen DEBE informar al agente de usuario a través del código de respuesta HTTP 201 (Created) y si un recurso existente es modificado, los códigos de respuesta 200 (OK) o 204 (No Content) DEBERÍAN ser enviados para indicar la finalización exitosa de la solicitud.
Si la solicitud pasa a través de una caché y el Request-URI identifica una o más entidades actualmente almacenadas en caché, esas entradas DEBERÍAN ser tratadas como antiguas. Las respuestas a este método no son almacenables en caché.
Ejemplo de URIs de petición
- HTTP PUT http://www.appdomain.com/users/123
- HTTP PUT http://www.appdomain.com/users/123/accounts/456
HTTP DELETE
Como su nombre indica, las APIs DELETE se utilizan para eliminar recursos (identificados por la Request-URI).
Una respuesta exitosa de las solicitudes DELETE DEBERÍA ser la respuesta HTTP code 200 (OK)si la respuesta incluye una entidad que describa el estado, 202 (Accepted)si la acción ha sido puesta en cola, o 204 (No Content)si la acción ha sido realizada pero la respuesta no incluye una entidad.
Las operaciones DELETE son idempotentes. Si se DELETA un recurso, se elimina de la colección de recursos. Llamar repetidamente a la API DELETE sobre ese recurso no cambiará el resultado – sin embargo, llamar a DELETE sobre un recurso por segunda vez devolverá un 404 (NO ENCONTRADO) puesto que ya fue eliminado. Algunos pueden argumentar que esto hace que el método DELETE no sea idempotente. Es una cuestión de discusión y opinión personal.
Si la petición pasa a través de una caché y el Request-URI identifica una o más entidades actualmente almacenadas en caché, esas entradas DEBERÍAN ser tratadas como antiguas. Las respuestas a este método no son almacenables en caché.
Ejemplo de URI de solicitud
- HTTP DELETE http://www.appdomain.com/users/123
- HTTP DELETE http://www.appdomain.com/users/123/accounts/456
HTTP PATCH
Las solicitudes PATCH son para hacer una actualización parcial en un recurso. Si ves que las peticiones PUT también modifican una entidad de recurso, así que para dejarlo más claro – el método PATCH es la opción correcta para actualizar parcialmente un recurso existente, y PUT sólo debe usarse si estás reemplazando un recurso en su totalidad.
Por favor, ten en cuenta que hay algunos desafíos si decides usar las APIs PATCH en tu aplicación:
- El soporte para PATCH en los navegadores, servidores y frameworks de aplicaciones web no es universal. IE8, PHP, Tomcat, Django, y un montón de otro software ha perdido o roto el apoyo a la misma.
- La carga útil de una solicitud PATCH no es directa como lo es para la solicitud PUT. por ejemplo
HTTP GET /users/1Produce la siguiente respuesta:
{id: 1, username: 'admin', email: ''}Un ejemplo de solicitud de parche para actualizar el correo electrónico será así:
HTTP PATCH /users/1» }
]
Pueden existir las siguientes operaciones posibles según la especificación HTTP.
},
{ "op": "replace", "path": "/a/b/c", "value": 42 },
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
{ "op": "copy","from": "/a/b/d", "path": "/a/b/e" }
]
El método PATCH no sustituye a los métodos POST o PUT. Aplica un delta (diff) en lugar de reemplazar todo el recurso.
Resumen de los métodos HTTP para las APIs RESTful
La siguiente tabla resume el uso de los métodos HTTP comentados anteriormente.
| Método HTTP | CRUD | Recogida de datos (ej. /users) | Artículo específico (por ejemplo, /users/123) |
|---|---|---|---|
| POST | Create | 201 (Creado), cabecera ‘Location’ con enlace a /users/{id} que contiene el nuevo ID. | Evitar el uso de POST en un solo recurso |
| GET | Read | 200 (OK), lista de usuarios. Utilice la paginación, la ordenación y el filtrado para navegar por las listas grandes. | 200 (OK), un solo usuario. 404 (No encontrado), si el ID no se encuentra o no es válido. |
| PUT | Actualizar/Reemplazar | 405 (Método no permitido), a menos que quiera actualizar cada recurso en toda la colección de recursos. | 200 (OK) o 204 (Sin contenido). Utilice 404 (No encontrado), si el ID no se encuentra o no es válido. |
| PATCH | Actualización/Modificación Parcial | 405 (Método no permitido), a menos que desee modificar la propia colección. | 200 (OK) o 204 (Sin contenido). Utilice 404 (No encontrado), si el ID no se encuentra o no es válido. |
| DELETE | Borrar | 405 (Método no permitido), a menos que desee eliminar toda la colección – utilice con precaución. | 200 (OK). 404 (No encontrado), si el ID no se encuentra o no es válido. |
Glosario
Métodos seguros
Según la especificación HTTP, los métodos GET y HEAD deben utilizarse sólo para recuperar representaciones de recursos – y no actualizan/borran el recurso en el servidor. Se dice que ambos métodos se consideran «seguros».
Esto permite a los agentes de usuario representar otros métodos, como POST, PUT y DELETE, de una manera única para que el usuario sea consciente del hecho de que se está solicitando una acción posiblemente insegura – y pueden actualizar/borrar el recurso en el servidor, por lo que deben utilizarse con cuidado.
Métodos idempotentes
El término idempotente se utiliza más ampliamente para describir una operación que producirá los mismos resultados si se ejecuta una o varias veces. La idempotencia es una propiedad útil en muchas situaciones, ya que significa que una operación puede ser repetida o reintentada tantas veces como sea necesario sin causar efectos no deseados. Con las operaciones no idempotentes, el algoritmo puede tener que hacer un seguimiento de si la operación ya fue realizada o no.
En la especificación HTTP, Los métodos GET, HEAD, PUT y DELETE son declarados métodos idempotentes. Otros métodos OPTIONS y TRACE NO DEBEN tener efectos secundarios, por lo que ambos son también inherentemente idempotentes.