Header Ads Widget

Ticker

6/recent/ticker-posts

Guía definitiva de 9 métodos HTTP comunes

 

Tendemos a dar por sentados los métodos HTTP . En el espacio de desarrollo de API, los métodos son similares al alfabeto: se usan con frecuencia, rara vez se consideran. Los desarrolladores de API generalmente solo usan GET , PUT o POST , pero el registro oficial del método de solicitud HTTP enumera 39 verbos HTTP en total , cada uno de los cuales proporciona un método para interacciones poderosas. En este artículo, revisamos 9 de los más comunes.

A continuación, revisamos 9 métodos HTTP estándar y profundizamos un poco en lo que hace cada método. Para nuestros ejemplos, usaremos la API PetStore para proporcionar algunas llamadas de API de muestra que demuestran estos métodos. Tenga en cuenta que los métodos de API se pueden utilizar de diversas formas, por lo que su caso de uso puede diferir en función. No obstante, estos métodos están bien definidos y, como tales, los ejemplos que se dan aquí son algunos de los más comunes.

Métodos de recuperación de recursos

Quizás el más obvio de los métodos que vamos a discutir hoy, GET y HEAD están diseñados para recuperar un recurso de una manera particular. Esta es una de las funciones más comúnmente comprendidas, así como algunas de las más utilizadas.

OBTENER

El método GET está diseñado para solicitar un recurso específico. En esencia, literalmente “obtiene” el recurso en cuestión y está bastante limitado a esa acción. Las solicitudes GET solo deben recuperar datos, dejando otros métodos para realizar las otras acciones transformadoras.

Ejemplo

En este ejemplo, vamos a emitir una solicitud GET para ver el estado actual de un animal específico en la API PetStore usando curl .

Solicitud:

curl -X GET "https://petstore.swagger.io/v2/pet/10" -H "accept: application/json"

Respuesta:

{
  "id": 10,
  "category": {
    "id": 0,
    "name": "pudle"
  },
  "name": "doggie",
  "photoUrls": [
    "string"
  ],
  "tags": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "status": "available"
}

CABEZA

HEAD es un método interesante en el sentido de que refleja algunas funciones de otro MÉTODO al tiempo que abre posibilidades adicionales. HEAD solicita una respuesta GET de un recurso determinado, pero con el cuerpo de respuesta eliminado. Si bien eso puede parecer demasiado simplista, permite una mayor flexibilidad y potencia para otras extensiones de API; por ejemplo, puede pasar los encabezados de un recurso a otra solicitud en un intento de imitar un entorno o situación de solicitud diferente, lo cual es extremadamente útil para probar y resolución de problemas.

Ejemplo

Emitamos una solicitud para ver solo los encabezados de la entrada dada.

Solicitud:

curl -X HEAD "https://petstore.swagger.io/v2/pet/10"

Respuesta:

access-control-allow-headers: Content-Type, api_key, Authorization
access-control-allow-methods: GET, POST, DELETE, PUT
access-control-allow-origin: *
connection: close
content-type: application/json
date: Sun, 08 Dec 2019 16:10:08 GMT
server: Jetty(9.2.9.v20150224)
Lea también: Comprender los poderes ocultos del rizo

Métodos de modificación de recursos

Hay muchos métodos que pueden cambiar el recurso fundamentalmente. Estos métodos pueden incluir la ubicación de un recurso, el reemplazo de un recurso específico e incluso la actualización de atributos sobre el recurso.

PONER

PUT es el polo opuesto de GET. Mientras GET solicita un recurso específico, PUT coloca ese recurso en el directorio remoto. Cabe señalar que PUT asume que el recurso no existe o que el recurso está bien para ser sobrescrito; cuando se usa PUT, todas las representaciones del recurso objetivo serán reemplazadas por la carga útil.

Ejemplo

¡Hemos recibido un nuevo cachorro en PetStore! Actualicemos nuestros datos en el backend para reflejar esto.

Solicitud:

curl -X PUT "https://petstore.swagger.io/v2/pet" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"id\": 100, \"category\": { \"id\": 0, \"name\": \"shiba\" }, \"name\": \"inu\", \"photoUrls\": [ \"string\" ], \"tags\": [ { \"id\": 0, \"name\": \"string\" } ], \"status\": \"available\"}"

Respuesta:

{
  "id": 100,
  "category": {
    "id": 0,
    "name": "shiba"
  },
  "name": "inu",
  "photoUrls": [
    "string"
  ],
  "tags": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "status": "available"
}

PARCHE

PATCH está diseñado para modificar parcialmente un recurso específico. En otras palabras, mientras PUT coloca un recurso en el servicio de destino, PATCH modifica ese recurso, en lugar de reemplazarlo. Esta es una buena forma de actualizar archivos o versiones.

Ejemplo

¡Nuestro nuevo cachorro ha sido adoptado en su primer día! Necesitaremos actualizar el recurso para reflejar esto en la API.

Solicitud:

curl -X PATCH "https://petstore.swagger.io/v2/pet" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"id\": 100, \"category\": { \"id\": 0, \"name\": \"shiba\" }, \"name\": \"inu\", \"photoUrls\": [ \"string\" ], \"tags\": [ { \"id\": 0, \"name\": \"string\" } ], \"status\": \"unavailable\"}"

Respuesta:

{
  "id": 100,
  "category": {
    "id": 0,
    "name": "shiba"
  },
  "name": "inu",
  "photoUrls": [
    "string"
  ],
  "tags": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "status": "unavailable"
}

ELIMINAR

DELETE es el método más claro de esta lista porque hace exactamente lo que está en la lata: DELETE elimina un recurso específico. La respuesta típica para un método de eliminación es simplemente responder con un estado "OK", ya sea que el recurso se eliminó o no.

ENVIAR

POST afecta los recursos relacionados adjuntos a un recurso de destino. POST permite que una API envíe un atributo o entidad a un recurso determinado; en la práctica, esto significa que el recurso objetivo recibe un recurso subordinado que forma parte de una colección más grande. Como ejemplo, un uso de POST sería agregar una imagen a un recurso; en el caso de PetStore, es posible que deseemos agregar una foto que se pueda usar para ayudar a adoptar a nuestros cachorros de refugio.

Solicitud:

curl -X POST "https://petstore.swagger.io/v2/pet/10/uploadImage" -H  "accept: application/json" -H  "Content-Type: multipart/form-data" -F "file=@background.png;type=image/png"

Respuesta:

{
  "code": 200,
  "message": "additionalMetadata: null\nFile uploaded to ./background.png, 63705 bytes"
}

OPCIONES

El método OPTIONS cambia las diferentes opciones de comunicación que tiene el recurso de destino. Esto se puede utilizar tanto para abrir más canales de comunicación como para bloquearlos; por esta razón, el método OPTIONS debe considerarse similar a un grifo que se puede abrir y cerrar con relativa granularidad.

Lea también: ¿Cuál es la diferencia entre Stateful y Stateless?

Métodos de entorno de recursos

No todo cambio en un recurso tiene que ser un cambio en el contenido del recurso. Hay dos métodos básicos que interactúan más con el entorno del recurso que con el propio recurso.

RASTRO

TRACE es un método que realiza una prueba de bucle de mensajes. Esta prueba permite echar un vistazo a la ruta hacia el recurso objetivo, identificando puntos potenciales de falla. Esta es una herramienta muy poderosa, por simple que sea, ya que refleja la ruta esencial de un recurso.

CONECTAR

CONNECT es un método que crea comunicación con un recurso en lugar de interactuar directamente con dicho recurso. CONNECT establece un túnel al servidor que contiene el recurso objetivo.

Idempotencia: ¿cuándo necesita solicitudes idempotentes?

¿Qué es la idempotencia?

Si bien la idempotencia es un tema lo suficientemente complejo como para justificar su propio artículo (hemos escrito mucho sobre él aquí ), el concepto está estrechamente relacionado con los métodos HTTP y requiere una discusión rápida aquí. Las solicitudes idempotentes deben producir el mismo resultado una y otra vez, independientemente del entorno. En otras palabras, una solicitud idéntica debería emitir una respuesta idéntica de forma coherente. Esta respuesta idéntica debe tener una forma más que un resultado: la forma y la naturaleza deben seguir siendo las mismas, incluso si los datos subyacentes que se están transmitiendo no lo son.

Para citar nuestro artículo original sobre este tema:

“Una buena forma de enmarcar su comprensión de este concepto es pensar en cada llamada funcional como hacer una pregunta en otro idioma. Cuando le preguntas a alguien qué hora es en español - "¿que hora es?" - la respuesta a esa pregunta puede cambiar según la hora del día. Este sería un valor cambiante.

Sin embargo, la forma en la que espera la respuesta no cambia: solo porque son las 4 de la tarde, la persona que responde no va a empezar a usar "limones" como medida de horas, ni a responderle en francés. Cada respuesta estará estructurada en la forma, sintaxis y gramática que esperas, y no importa cuántas veces preguntes, siempre estará en español. Esta es la función de la llamada. Uno puede imaginar el caos que podría sobrevenir si una persona cambia constantemente entre español, francés, alemán e inglés dependiendo de la hora del día y de lo que se le pregunta; en esta situación, sería imposible formarse expectativas efectivas y coherentes.
Lo mismo ocurre en el espacio API. La llamada funcional no debe ser diferente con cada solicitud, sino que debe regresar de una manera conocida y esperada, independientemente de cuán diferente pueda ser el valor de respuesta ".

Debemos tener en cuenta que la idempotencia es diferente de la seguridad, que es un término similar que se usa con bastante frecuencia cuando se habla de métodos HTTP. Los métodos seguros simplemente no alteran el estado del servidor. Es posible ser idempotente además de seguro, pero también es posible ser uno y no otro. La siguiente infografía muestra qué métodos son idempotentes y cuáles son seguros; podemos ver con bastante facilidad que GET y HEAD, los únicos métodos que interactúan con el recurso sin alterar realmente el contenido del recurso, son los únicos métodos "seguros", incluso aunque también son idempotentes. Por otro lado, POST y PATCH, dos métodos que producen resultados muy diferentes cada vez que se utilizan, no son seguros.

¿Cuándo deben ser idempotentes los métodos? ¿Cuándo deberían estar a salvo?

Los métodos (y las operaciones que los involucran) existen para un propósito muy específico, y tanto la idempotencia como la seguridad de ellos deben estar estrechamente vinculados con la tabla de métodos como se describe anteriormente. Hay algunos casos muy claros en los que podemos decir que un método debería dar como resultado absolutamente lo mismo de forma coherente; por ejemplo, GET y HEAD son métodos muy relacionados con la obtención de información y no con la alteración de la información. En estos casos, la aplicación del método es bastante corta y seca. ¿Qué pasa con el término medio?

PUT y DELETE son ambos casos en los que el resultado es el mismo una y otra vez, pero el resultado funcional no lo es. GET y HEAD deberían producir exactamente el mismo resultado en un recurso siempre que ese recurso no haya cambiado; sin embargo, PUT y DELETE dan como resultado un resultado que esencialmente confirma el estado de un nuevo recurso o entidad. PUT coloca un recurso en algún lugar y DELETE elimina ese recurso; como tal, la idempotencia aquí debería ser un estado de éxito o de fracaso. En otras palabras, la confirmación y el resultado son diferentes aquí.

POST y PATCH, sin embargo, por diseño, no deberían resultar en llamadas idénticas debido a lo que hacen. Ambos cambian el contenido fundamentalmente y podrían responder de manera diferente dependiendo de si el atributo que se está cambiando existe actualmente o no. Como tales, no son idempotentes, y si lo fueran, no podrían hacer lo que están diseñados para hacer.

De nuestra lista completa, solo dos métodos son realmente seguros: GET y HEAD. Estos dos métodos no cambian el estado del recurso ni dan lugar a diferencias siempre que el recurso permanezca sin cambios y, como tal, estén solos en su seguridad.

Conclusión

Los métodos HTTP impulsan las interacciones API fundamentales que vemos día tras día. Comprender estos métodos, su idempotencia y su seguridad es un paso clave para comprender el espacio API con una apreciación sustancialmente más profunda.

Las suposiciones comunes y el “entendimiento general” han llevado a que algunos de estos métodos y términos relacionados se malinterpreten, se utilicen y se apliquen incorrectamente. Sin embargo, con unos pocos conceptos básicos simples, los conceptos se pueden aprender y comprender fácilmente.

¿Qué opinas de estos métodos? Otro argumento en torno a ellos es si se llaman "métodos" o "verbos"; aquí hemos elegido métodos, pero nos interesa saber cómo los llama. ¡Háganos saber a continuación!

Publicar un comentario

0 Comentarios