Nikhil y Leonid han dado algunas buenas respuestas sobre cómo se diseñan las API REST. Agregaré algunos detalles sobre cómo trabajar con las API.
(Esto se toma de Trabajar con API donde el formato es un poco más agradable. Para solucionar problemas de API, consulte Solución de problemas de API)
Las API REST, al igual que los sitios web normales, usan HTTP para la comunicación. Por lo general, el funcionamiento interno de HTTP está oculto para nosotros, como usuarios. Sin embargo, al probar o depurar APIs es necesario comprender exactamente qué comprende una solicitud HTTP a un servidor y cómo un servidor responde a dicha solicitud.
- ¿Por qué la gente odia su CMS?
- Cómo publicar una matriz multidimensional de botones de opción y casillas de verificación en MySQL usando PHP sin alterar los índices
- ¿Qué problemas aún deben resolverse con el sitio web de YouTube?
- ¿Existe una diferencia notable en el rendimiento y la latencia entre el alojamiento de Redis en un servidor de base de datos central y el local en cada servidor web?
- ¿Cómo puede una empresa de diseño web ofrecer la mejor calidad?
Solicitudes HTTP
Todas las solicitudes HTTP deben tener al menos dos líneas. La primera línea muestra el método de solicitud, una ruta en el servidor y la versión de HTTP a utilizar. En el siguiente ejemplo, estos valores son GET , /index.html y HTTP / 1.1 respectivamente. Además, una solicitud HTTP debe indicar el host al que se debe hacer la conexión (opcionalmente, también se puede especificar el puerto en el host).
OBTENER /index.html HTTP / 1.1
Anfitrión: Pruebas API
Solicitar encabezados
La línea Host es un ejemplo de un encabezado de solicitud HTTP. Una solicitud puede tener muchos otros encabezados, pero solo el encabezado Host es obligatorio. Consulte wikipedia para obtener una lista de encabezados de solicitud HTTP estándar. Un encabezado con el que probablemente ya esté familiarizado es el encabezado de agente de usuario que describe el software (por ejemplo, un navegador, como Internet Explorer) que se está utilizando para conectarse al servidor. Otros encabezados de solicitud de nota particular son Aceptar, Autorización y Tipo de contenido.
- Aceptar encabezado. El encabezado Aceptar indica los tipos de contenido que son aceptables en la respuesta del servidor. Algunas API usan el encabezado Aceptar para indicar la versión de una API que se debe usar. (Para ver un ejemplo de esto y una versión agradable del estado de las versiones de API, consulte Troy Hunt)
- Encabezado de autorización. Algunas API requieren que las credenciales de autenticación de un usuario (como nombre de usuario y contraseña o token de acceso) se proporcionen en el encabezado de Autorización.
- Encabezado de tipo de contenido. Además de los encabezados, una solicitud HTTP puede incluir un cuerpo de datos. El encabezado Content-Type se usa para indicar al servidor cómo se formatea el cuerpo de la solicitud. Por ejemplo, si el cuerpo está en formato JSON, el tipo de contenido de la solicitud debe ser application / json .
Además de los encabezados de solicitud estándar, también es posible incluir encabezados personalizados (es decir, cualquier par clave-valor arbitrario). Un uso de los encabezados personalizados es especificar la versión de la API que se utilizará. Nuevamente, vea Troy Hunt para ver un ejemplo de esto.
Métodos de solicitud
En el ejemplo anterior, el método de solicitud es GET. Los métodos de solicitud más utilizados con las API son GET, POST, PUT, PATCH y DELETE. No hay reglas absolutas sobre cómo se usa cada uno de estos métodos, pero por convención los métodos se usan de la siguiente manera.
- GET se usa para leer del servidor un solo elemento (conocido como recurso en API speak) o una lista de elementos (conocida como una colección ). Al leer un recurso específico, el identificador único del recurso se especifica como parte de la URL. Los GET normalmente no tienen un cuerpo de solicitud.
- POST se utiliza para escribir en el servidor un nuevo recurso. Los detalles del nuevo recurso se incluyen en el cuerpo de la solicitud. La respuesta del servidor debe incluir el identificador único del recurso recién creado.
- PUT y PATCH se usan para actualizar un recurso. El identificador único del recurso generalmente se especifica en la URL y los campos actualizados se proporcionan en el cuerpo de la solicitud.
- DELETE se usa para eliminar un recurso con el identificador único del recurso que se especifica en la URL y la solicitud no tiene cuerpo. Algunas API también usan el método DELETE para eliminar varios recursos a la vez. En este caso, los identificadores únicos de cada recurso a eliminar se especifican en el cuerpo de la solicitud.
Respuestas HTTP
Una respuesta HTTP consta de una línea de estado, encabezados de respuesta y, en la mayoría de los casos, un cuerpo de respuesta.
Estado de respuesta
La línea de estado de una respuesta incluye el código de estado que indica el resultado general del procesamiento de la solicitud. Los códigos de estado de respuesta se agrupan en cinco categorías con el primer dígito del código que indica la clase de respuesta,
- 1xx La solicitud se recibió y se está procesando. Los códigos en este rango rara vez se ven.
- 2xx La solicitud se procesó correctamente.
- Se requiere la redirección 3xx a otra URL. (Las diferentes herramientas que usamos para interactuar con las API normalmente manejan las redirecciones de forma automática y, por lo tanto, es inusual cuando se trabaja con API para que se les presente un código de estado en el rango 3xx).
- 4xx Hubo un error en la solicitud.
- 5xx El servidor no pudo cumplir la solicitud debido a un problema en el lado del servidor.
A través de la navegación web general, todos hemos encontrado el código de estado 404 (página no encontrada) y muy probablemente el código de estado ocasional 500 (error interno del servidor). Los códigos de estado comunes cuando se trata con API son,
- 200 Éxito. Este es el estado estándar cuando la respuesta es normal y no se encontró ningún problema.
- 201 Recurso creado. Por lo general, en respuesta a una solicitud POST, esto indica que se creó un recurso.
- 400 La solicitud original era incorrecta o mal formada de alguna manera.
- 401 Las credenciales de autenticación del usuario no se proporcionaron o no fueron válidas. es decir, el equivalente API de ID de usuario / contraseña no es válido 1.
- 403 No tiene autoridad para hacerlo (por ejemplo, un usuario normal intenta realizar una acción solo disponible para usuarios administradores)
- 404 En un contexto API, un estado 404 puede tener dos significados. El primero es similar a ‘página no encontrada’ y significa que la URL no existe. La URL puede estar completamente equivocada o quizás una URL correcta tiene un error tipográfico. Por ejemplo, la URL para enumerar todas las empresas puede haberse ingresado como / api / kompany pero debería haber sido / api / company.
El otro significado de un 404 en un contexto API es que, aunque la URL está bien formada, el recurso identificado por la URL no existe. Por ejemplo, la URL para obtener una empresa con un identificador único de 54321 puede ser / api / company / 54321, pero si esa empresa no existe (quizás se eliminó), el servidor debería devolver un 404. - 500 Es probable que el programa que maneja la solicitud arrojó una excepción no detectada (es decir, hay un error en el código del lado del servidor; incluso si la solicitud original era de alguna manera incorrecta, el servidor debería devolver un estado en el rango 4xx y no un 500) .
- 502 Normalmente indicativo de un error que surge entre dos de los servidores involucrados en responder a una solicitud.
- 503 Un recurso técnico o servicio en el lado del servidor no está disponible en este momento. Esto puede ser una condición temporal.
Es importante tener en cuenta dos cosas sobre los códigos de estado al depurar las API.
En primer lugar, no hay forma de aplicar estrictamente el uso de un código de estado dado para una situación dada. Los códigos utilizados pueden incluso variar dentro de la misma API. Los desarrolladores pueden tener diferentes interpretaciones sobre qué código de estado se debe usar para diferentes eventos y algunos desarrolladores pueden desconocer que ciertos códigos de estado están disponibles. En el caso de crear un recurso con una solicitud POST, a menudo se usa un código 200 en lugar del código correcto, 201. Es poco probable que la diferencia entre 200 y 201 sea un problema. Más problemáticos son los errores de la serie 4xx cuando una solicitud no está bien formada. Por ejemplo, si el valor 13 se especificó para un campo que representa un número de mes, ¿cuál debería ser el código de estado? Probablemente un 400 pero no se sorprenda al ver un 403 devuelto. Incluso un 500 es posible si el servidor termina generando una excepción debido al valor defectuoso.
La segunda cosa a tener en cuenta sobre los códigos de estado es que no todos son generados por el código que sus programadores de back-end han escrito. Cuando se realiza una solicitud HTTP, normalmente se procesa primero por software de servidor web, como Apache o Nginx. Solo si la solicitud se ve bien para el servidor web, se pasará al servidor de aplicaciones. Antes de que la solicitud llegue al código de los desarrolladores de back-end, es probable que pase a través de una capa de middleware que puede tener su propio código de comprobación de errores. Finalmente, el código de sus desarrolladores manejará cualquier solicitud que pase el servidor web y el middleware.
Considere algunos ejemplos,
- Si una solicitud es más grande de lo que Apache está configurado para manejar, Apache responderá con un código de estado 413 y la solicitud nunca llegará al servidor de aplicaciones.
- Puede ser que Nginx responda con un código de estado 404 para un punto final inexistente (/ api / kompany en nuestro ejemplo anterior) pero el código de la aplicación es responsable de devolver un 404 para indicar que un recurso en particular no existe (/ api / empresa / 54321 en nuestro ejemplo anterior).
- El middleware puede ser cuerpos de solicitud de preprocesamiento. Dependiendo del middleware, puede rechazar solicitudes con un encabezado de tipo de contenido de aplicación / json si el cuerpo de la solicitud tiene un formato JSON incorrecto.
Comprender dónde se pueden generar los códigos de estado es fundamental al crear planes de prueba de API y al depurar API.
Encabezados de respuesta
Hay varios encabezados de respuesta estándar y la mayoría de los servidores usan varios encabezados para cada respuesta. Además, también se pueden usar encabezados personalizados. En el mundo API, uno de los usos más comunes de los encabezados personalizados es proporcionar información de paginación al devolver una colección para indicar el número total de páginas que están disponibles y el rango particular de elementos en la respuesta actual.
Si una API no se comporta como se esperaba, ciertamente vale la pena examinar los encabezados de respuesta en busca de pistas sobre un problema, pero en el uso normal el encabezado Content-Type es probablemente el más útil. Este encabezado indica cómo se formatea el cuerpo de la respuesta. Por ejemplo, el encabezado Content-Type para un cuerpo JSON es probable que sea application / json; juego de caracteres = UTF-8 .
Navegadores API
Al explorar y depurar las API, necesita una herramienta que le permita interactuar con la API y manipular el encabezado y el cuerpo de la solicitud. Hay muchas opciones.
- rizo. Esta herramienta de línea de comandos viene de serie con el sistema operativo Mac OS X y con todos los sabores de UNIX.
- El violinista de Telerik. Esta es una descarga potente y gratuita que es ideal para depurar sitios web y API.
- Software comercial Para algunas llamadas rápidas a una API, curl o Fiddler son excelentes, pero si planea probar y monitorear a fondo una API, hay una serie de herramientas comerciales disponibles.
rizo
Si tienes una Mac, entonces ya tienes acceso a curl. Haga clic en la aplicación Terminal desde Aplicaciones / Utilidades, para abrir una ventana de terminal.
Ingrese curl -v mock.one/200
en la ventana de terminal y verá una salida similar a la siguiente. La -v indica que la salida debe ser detallada (la salida detallada de curl incluye los encabezados de solicitud y respuesta). El dominio mock.one es un servidor configurado con fines de prueba y la URL mock.one/200
se ha configurado con fines de prueba y simplemente devuelve la cadena que you have been served a 200
mock.one/200
you have been served a 200
.
* Intentando 52.1.95.2 …
* Conectado a mock.one (52.1.95.2) puerto 80 (# 0)
> GET / 200 HTTP / 1.1
> Anfitrión: mock.one
> Usuario-Agente: curl / 7.43.0
> Aceptar: * / *
>
<HTTP / 1.1 200 OK
<Fecha: sáb, 03 oct 2015 06:13:00 GMT
<Servidor: Embarcadero
<Tipo de contenido: texto / html; charset = UTF-8
<Contenido-Longitud: 26
<Variar: aceptar-codificación
<Conexión: cerrar
<* Conexión de cierre 0
te han servido 200
Puede ver en este resultado que el comando curl incluyó automáticamente tres encabezados de respuesta en nuestro nombre. El primero es el encabezado Host obligatorio, los otros dos son los encabezados User-Agent y Accept . El tipo de solicitud es GET y no hay cuerpo de solicitud.
La primera línea de respuesta del servidor es la línea de estado que muestra el código de estado como 200. También se incluye el texto equivalente a 200, OK . Los encabezados de respuesta son Fecha , Servidor , Tipo de contenido, Longitud de contenido , Variar y Conexión . El cuerpo real de la respuesta es solo la cadena de texto que se le ha entregado un 200.
Dado que esta solicitud es una solicitud GET, en realidad puede ver la misma URL utilizando un navegador normal. Haz clic aquí para hacerlo. (Cuando ingresa una URL en un navegador normal, el navegador envía una solicitud GET al servidor).
Ahora intentemos una solicitud POST con el siguiente comando,
curl -v -X POST -H "Content-Type: application/json" --data '{"name":"Megacorp","Employees":950000}' --user supersecret: mock.one/api/company
Como puede resolver, el indicador -X
se usa para el método de solicitud, -H para un encabezado, --data
para el cuerpo y --user
para las credenciales. El resultado de este comando se ve así,
* Intentando 52.1.95.2 …
* Conectado a mock.one (52.1.95.2) puerto 80 (# 0)
* Autenticación del servidor usando Basic con el usuario ‘supersecret’
> POST / api / empresa HTTP / 1.1
> Anfitrión: mock.one
> Autorización: Basic c3VwZXJzZWNyZXQ6
> Usuario-Agente: curl / 7.43.0
> Aceptar: * / *
> Tipo de contenido: application / json
> Contenido-Longitud: 38
>
* carga completamente enviada: 38 de 38 bytes
<HTTP / 1.1 200 OK
<Fecha: sáb, 03 oct 2015 06:30:24 GMT
<Servidor: Embarcadero
<Tipo de contenido: aplicación / json; charset = utf-8
<Contenido-Longitud: 38
<Conexión: cerrar
<
* Conexión de cierre 0
{“nombre”: “Megacorp”, “Empleados”: 950000}
Observe que curl inserta automáticamente un encabezado de autorización en el formato correcto, incluida la conversión de supersecret a su equivalente de codificación Base64.
El servidor simulado utilizado en esta prueba simplemente responde con un cuerpo que es el mismo que el cuerpo de la solicitud. Es por eso que ve el mismo JSON en la respuesta que se envió originalmente en la solicitud POST original.
Como puede ver, curl es una gran herramienta para explorar las API y proporciona una manera fácil de ver los encabezados de solicitud y respuesta.