Comprensión y uso de las API REST

Es muy probable que haya encontrado el término "API REST" si ha pensado en obtener datos de otra fuente en Internet, como Twitter o Github. Pero, ¿qué es una API REST? ¿Qué puedo hacer por ti? ¿Como lo usas?

En este artículo, aprenderá todo lo que necesita saber sobre las API REST para poder leer la documentación de las API y usarlas de manera efectiva.

¿Qué es una API REST?

Digamos que estás tratando de encontrar videos sobre Batman en Youtube. Abre Youtube, escribe "Batman" en un campo de búsqueda, presiona enter y ve una lista de videos sobre Batman. Una API REST funciona de manera similar. Busca algo y obtiene una lista de resultados del servicio que está solicitando.

Una API es una interfaz de programación de aplicaciones. Es un conjunto de reglas que permiten que los programas se comuniquen entre sí. El desarrollador crea la API en el servidor y permite que el cliente se comunique con ella.

REST determina cómo se ve la API. Significa "Transferencia de estado representacional". Es un conjunto de reglas que siguen los desarrolladores cuando crean su API. Una de estas reglas establece que debería poder obtener un dato (llamado recurso) cuando se vincula a una URL específica.

Cada URL se denomina solicitud , mientras que los datos que se le envían se denominan respuesta .

La anatomía de una solicitud

Es importante saber que una solicitud se compone de cuatro cosas:

1. el punto final
2. El método
3. los encabezados
4. Los datos (o el cuerpo)

El punto final (o ruta) es la URL que solicita. Sigue esta estructura:

 root-endpoint/ ? root-endpoint/ ? root-endpoint/ ?

El punto de conexión raíz es el punto de partida de la API desde la que realiza la solicitud. El extremo raíz de la API de Github es https://api.github.com , mientras que el extremo raíz de la API de Twitter es https://api.twitter.com .

La ruta determina el recurso que está solicitando. Piense en ello como un contestador automático que le pide que presione 1 para un servicio, presione 2 para otro servicio, 3 para otro servicio y así sucesivamente.

Puede acceder a las rutas de la misma manera que puede enlazar a partes de un sitio web. Por ejemplo, para obtener una lista de todas las publicaciones etiquetadas como "JavaScript" en Smashing Magazine, vaya a https://www.smashingmagazine.com/tag/javascript/ . https://www.smashingmagazine.com/ es el punto final raíz y /tag/javascript es la ruta.

Para comprender qué rutas están disponibles para usted, debe consultar la documentación de la API. Por ejemplo, supongamos que desea obtener una lista de repositorios de un determinado usuario a través de la API de Github. Los documentos le dicen que use la siguiente ruta para hacerlo:

 /users/:username/repos

Los dos puntos ( : ) en una ruta denotan una variable. Debe reemplazar estos valores con los valores reales de cuando envía su solicitud. En este caso, debe reemplazar :username con el nombre de usuario real del usuario que está buscando. Si busco mi cuenta de Github, reemplazaré :username con zellwk .

El punto final para obtener una lista de mis repositorios en Github es este:

 https://api.github.com/users/zellwk/repos

La parte final de un punto final son los parámetros de consulta . Técnicamente, los parámetros de consulta no forman parte de la arquitectura REST, pero verá que muchas API los utilizan. Entonces, para ayudarlo a comprender completamente cómo leer y usar las API, también hablaremos sobre ellas. Los parámetros de consulta le dan la opción de modificar su solicitud con pares clave-valor. Siempre comienzan con un signo de interrogación ( ? ). Luego, cada par de parámetros se separa con un ampersand ( & ), así:

 ?query1=value1&query2=value2

Cuando intentas obtener una lista de los repositorios de un usuario en Github, agregas tres parámetros posibles a tu solicitud para modificar los resultados que te dan:

Si desea obtener una lista de los repositorios a los que impulsé recientemente, puede configurar sort para push .

 https://api.github.com/users/zellwk/repos?sort=pushed

¿Cómo saber si este punto final funciona? Bueno, es hora de darle una oportunidad!

Prueba de puntos finales con curl

Puede enviar una solicitud con cualquier lenguaje de programación. Los usuarios de JavaScript pueden usar métodos como Fetch API y el método Ajax de jQuery; Los usuarios de Ruby pueden usar la clase Net::HTTP de Ruby, los usuarios de Python pueden usar solicitudes de Python; y así.

Para este artículo, usaremos la utilidad de línea de comando llamada cURL. Usamos cURL porque la documentación de la API normalmente se escribe con referencia a cURL. Si comprende cómo usar cURL, no tendrá problemas para comprender la documentación de la API. Luego, puede realizar fácilmente solicitudes con su idioma preferido.

Antes de continuar, querrá asegurarse de tener cURL instalado en su máquina. Abre tu Terminal y escribe curl -version . Este comando verifica la versión de cURL que ha instalado en su sistema.

 curl --version

Si no tiene cURL instalado, obtendrá un error de "comando no encontrado". Si recibe este error, deberá instalar curl antes de continuar.

Para usar cURL, escriba curl , seguido del punto final que está solicitando. Por ejemplo, para obtener el extremo raíz de Github, escriba lo siguiente:

 curl https://api.github.com

Una vez que presionas enter, deberías obtener una respuesta de Github que se ve así:

Para obtener una lista de los repositorios de un usuario, modifica el punto final a la ruta correcta, como lo discutimos anteriormente. Para obtener una lista de mis repositorios, puede usar este comando:

 curl https://api.github.com/users/zellwk/repos

Si desea incluir parámetros de consulta con cURL, asegúrese de anteponer una barra invertida ( \ ) antes de ? y = caracteres. Esto es porque ? y = son caracteres especiales en la línea de comando. Debe usar \ antes de ellos para que la línea de comando los interprete como caracteres normales:

 curl https://api.github.com/users/zellwk/repos\?sort\=pushed

¡Intenta usar cualquiera de los comandos y realiza una solicitud! Obtendrá una respuesta similar a la que ha visto con el root-endpont de Github (pero con muchos más datos).

JSON

JSON (Notación de objetos de JavaScript) un formato común para enviar y solicitar datos a través de una API REST. La respuesta que te envía Github también está formateada como JSON.

Un objeto JSON se parece a un objeto JavaScript. En JSON, cada propiedad y valor debe estar entre comillas dobles, así:

 { "property1": "value1", "property2": "value2", "property3": "value3" }

Volver a la anatomía de una solicitud

Has aprendido que una solicitud consta de cuatro partes.

1. el punto final
2. El método
3. los encabezados
4. Los datos (o el cuerpo)

Repasemos el resto de lo que constituye una solicitud.

El método

El método es el tipo de solicitud que envía al servidor. Puede elegir entre estos cinco tipos a continuación:

• GET
• POST
• PUT
• PATCH
• DELETE

Estos métodos proporcionan significado a la solicitud que está realizando. Se utilizan para realizar cuatro acciones posibles: Create , Read , Update y Delete (CRUD).

La API le permite saber qué método de solicitud usar en cada solicitud. Por ejemplo, para obtener una lista de los repositorios de un usuario, necesita una solicitud GET :

Se requiere una solicitud GET para obtener una lista de repositorios de un usuario. Para crear un nuevo repositorio de Github, necesita una solicitud POST :

Puede configurar el método de solicitud en cURL escribiendo -X o --request , seguido del método de solicitud. Este comando a continuación intenta crear un repositorio a través de cURL:

 curl -X POST https://api.github.com/user/repos

Intenta ejecutar esta solicitud. Recibirá una respuesta que le indica que se requiere autenticación. (Más sobre la autenticación más adelante).

 { "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3" }

Los encabezados

Los encabezados se utilizan para proporcionar información tanto al cliente como al servidor. Se puede utilizar para muchos fines, como la autenticación y el suministro de información sobre el contenido del cuerpo. Puede encontrar una lista de encabezados válidos en la Referencia de encabezados HTTP de MDN.

Los encabezados HTTP son pares de propiedades y valores separados por dos puntos. El siguiente ejemplo muestra un encabezado que le dice al servidor que espere contenido JSON.

 "Content-Type: application/json". Missing the opening ".

Puede enviar encabezados HTTP con curl a través de la opción -H o --header . Para enviar el encabezado anterior a la API de Github, usa este comando:

 curl -H "Content-Type: application/json" https://api.github.com

(Nota: el encabezado Content-Type no es un requisito para que funcione la API de Github. Este es solo un ejemplo para ilustrar cómo usar un encabezado con cURL).

Para ver los encabezados que ha enviado, puede usar la opción -v o --verbose al enviar la solicitud, así:

 curl -H "Content-Type: application/json" https://api.github.com -v 

Aquí, * se refiere a información adicional proporcionada por cURL. > se refiere a los encabezados de solicitud y < se refiere a los encabezados de respuesta.

Los datos (o "cuerpo")

Los datos (a veces llamados "cuerpo" o "mensaje") contienen información que desea enviar al servidor. Esta opción solo se usa con POST , PUT , PATCH o DELETE .

Para enviar datos a través de cURL, puede usar la opción -d o --data :

 curl -X POST <URL> -d property1=value1

Para enviar múltiples campos de datos, puede crear múltiples opciones -d :

 curl -X POST <URL> -d property1=value1 -d property2=value2

Si tiene sentido, puede dividir su solicitud en varias líneas \ para que sea más fácil de leer:

 curl -X POST <URL> \ -d property1=value1 \ -d property2=value2

Si sabe cómo activar un servidor, puede crear una API y probar sus propios datos. Si no lo sabe, pero se siente lo suficientemente valiente como para intentarlo, puede seguir este artículo para aprender a crear un servidor con Node, Express y MongoDB.

Si no desea acelerar su servidor, puede ir a Requestbin.com ( ¡es gratis! ) y hacer clic en "crear punto final". Se le dará una URL que puede usar para probar las solicitudes, como https://requestb.in/1ix963n1 que se muestra en la imagen a continuación.

Asegúrese de crear su propio contenedor de solicitudes si desea probar su solicitud. Los contenedores de solicitud solo permanecen abiertos durante 48 horas después de su creación. Para cuando lea este artículo, el contenedor que creé anteriormente ya no estará.

Ahora, intente enviar algunos datos a su contenedor de solicitudes, luego actualice la página web de su contenedor. Verás algunos datos, como este:

 curl -X POST https://requestb.in/1ix963n1 \ -d property1=value1 \ -d property2=value2 

De forma predeterminada, cURL envía datos como si se enviaran a través de "campos de formulario" en una página. Si desea enviar datos JSON, deberá configurar el Content-Type en application/json y deberá formatear sus datos como un objeto JSON, así:

 curl -X POST https://requestb.in/1ix963n1 \ -H "Content-Type: application/json" \ -d '{ "property1":"value1", "property2":"value2" }' 

Y eso es (¡casi!) todo lo que necesita saber sobre la estructura de una solicitud.

Ahora, ¿recuerdas cuando intentaste enviar una solicitud POST a través de la API de Github, recibiste un mensaje que decía "Requiere autenticación"? Bueno, ¡eso es porque no está autorizado para realizar la solicitud POST !

Autenticación

No permitiría que nadie acceda a su cuenta bancaria sin su permiso, ¿verdad? En la misma línea de pensamiento, los desarrolladores implementan medidas para garantizar que realice acciones solo cuando esté autorizado para hacerlo. Esto evita que otros se hagan pasar por ti.

Dado que las POST , PUT , PATCH y DELETE alteran la base de datos, los desarrolladores casi siempre las colocan detrás de un muro de autenticación. En algunos casos, una solicitud GET también requiere autenticación (como cuando accede a su cuenta bancaria para verificar su saldo actual, por ejemplo).

En la web, hay dos formas principales de autenticarse:

1. Con un nombre de usuario y contraseña (también llamada autenticación básica)
2. Con una ficha secreta

El método de token secreto incluye oAuth, que le permite autenticarse con redes sociales como Github, Google, Twitter, Facebook, etc.

Para este artículo, solo aprenderá a usar la autenticación básica con un nombre de usuario y una contraseña. Si está interesado en autenticarse con oAuth, le sugiero que lea "Lo que necesita saber sobre OAuth2 e iniciar sesión con Facebook" de Zack Grossbart.

Para realizar una autenticación básica con cURL, puede usar la opción -u , seguida de su nombre de usuario y contraseña, así:

 curl -x POST -u "username:password" https://api.github.com/user/repos

Intente autenticarse con su nombre de usuario y contraseña en la solicitud anterior. Una vez que tenga éxito en la autenticación, verá que la respuesta cambia de "Requiere autenticación" a "Problemas al analizar JSON".

Esto se debe a que aún no ha proporcionado ningún dato (que es requerido por todas las POST , PUT , PATCH y DELETE ) al servidor.

Con el conocimiento que ha aprendido hasta ahora, debería poder editar el código anterior para crear un repositorio de Github a través de su cURL. ¡Te dejo que lo pruebes tú mismo!

Ahora, hablemos de los códigos de estado HTTP y los mensajes de error.

Códigos de estado HTTP y mensajes de error

Algunos de los mensajes que ha recibido anteriormente, como "Requiere autenticación" y "Problemas al analizar JSON", son mensajes de error. Solo aparecen cuando algo está mal con su solicitud. Los códigos de estado HTTP le permiten conocer el estado de la respuesta rápidamente. El rango de 100+ a 500+. En general, los números siguen las siguientes reglas:

1. 200+ significa que la solicitud se ha realizado correctamente .
2. 300+ significa que la solicitud se redirige a otra URL
3. 400+ significa que se ha producido un error que se origina en el cliente
4. 500+ significa que se ha producido un error que se origina en el servidor

Puede depurar el estado de una respuesta con la opción detallada ( -v o --verbose ) o la opción head ( -I o --head ).

Por ejemplo, si intentó agregar -I a una solicitud POST sin proporcionar su nombre de usuario y contraseña, obtendrá un código de estado 401 (no autorizado):

Si su solicitud no es válida porque sus datos son incorrectos o faltan, generalmente obtiene un código de estado 400 (Solicitud incorrecta).

Para obtener más información sobre códigos de estado HTTP específicos, puede consultar la Referencia de estado HTTP de MDN.

Versiones de la API

Los desarrolladores actualizan sus API de vez en cuando. A veces, la API puede cambiar tanto que el desarrollador decide actualizar su API a otra versión. Si esto sucede y su aplicación falla, generalmente se debe a que ha escrito código para una API más antigua, pero su solicitud apunta a la API más nueva.

Puede solicitar una versión de API específica de dos maneras. La forma que elija depende de cómo esté escrita la API.

Estas dos formas son:

1. Directamente en el punto final
2. En un encabezado de solicitud

Twitter, por ejemplo, utiliza el primer método. Al momento de escribir este artículo, la API de Twitter se encuentra en la versión 1.1, lo cual es evidente a través de su punto final:

 https://api.twitter.com/1.1/account/settings.json

Github, por otro lado, usa el segundo método. Al momento de escribir, la API de Github se encuentra en la versión 3 y puede especificar la versión con un encabezado Accept :

 curl https://api.github.com -H Accept:application/vnd.github.v3+json

Terminando

En este artículo, aprendiste qué es una API REST y cómo usar cURL para realizar una solicitud con los métodos GET , POST , PUT , PATCH y DELETE . Además, también aprendió cómo autenticar sus solicitudes con la opción -u y qué significan los estados HTTP.

Espero que este artículo lo haya ayudado a aprender lo suficiente sobre las API REST y que pueda usarlas con fluidez a medida que crea sus aplicaciones. Siéntase libre de visitar mi blog o dejar sus comentarios a continuación si tiene alguna pregunta.