Comprensión y uso de las API REST

1. ¿Qué es una API REST?
2. La anatomía de una solicitud
3. Prueba de puntos finales con curl
4. JSON
5. Volver a la anatomía de una solicitud
6. Autenticación
7. Códigos de estado HTTP y mensajes de error
8. Versiones API
9. Terminando
   1. Otras lecturas

Todo lo que necesitas saber sobre las API REST, de principio a fin. Cómo y por qué utilizar las API REST, cómo lidiar con encabezados, mensajes de error y versiones de API. En este artículo, Zell Liew le mostrará todo lo que necesita saber sobre las API REST para poder leer la documentación de las API y utilizarlas de forma eficaz. Además, también aprenderá cómo autenticar sus solicitudes con la opción -u y qué significan los estados HTTP. ¡Empecemos!

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 utilizarlas de forma eficaz.

Parte de: Rest API y GraphQL

• Comprensión y uso de las API REST
• Consumir API REST en React con Fetch y Axios
• Introducción a GraphQL: por qué necesitamos un nuevo tipo de API (Parte 1)
• Introducción a GraphQL: la evolución del diseño de API (Parte 2)
• Presentamos la API basada en componentes
• Además, suscríbete a nuestra newsletter para no perderte las próximas.

¿Qué es una API REST?

Digamos que estás intentando encontrar vídeos sobre Batman en Youtube. Abres Youtube, escribes "Batman" en un campo de búsqueda, presionas Enter y ves 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 Representativa del Estado". Es un conjunto de reglas que los desarrolladores siguen 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 cuerpo)

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

root-endpoint/

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

La ruta determina el recurso que estás 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 más, y así sucesivamente.

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

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

/users/:username/repos

Cualquier signo de dos puntos ( :) en una ruta indica una variable. Debe reemplazar estos valores con valores reales de cuando envió su solicitud. En este caso, debes reemplazarlo :usernamecon el nombre de usuario real del usuario que estás buscando. Si estoy buscando mi cuenta de Github, la reemplazaré :usernamecon 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 son parte de la arquitectura REST, pero verás 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 brindan 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 símbolo ( ), así:

?query1=value1query2=value2

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

Si desea obtener una lista de los repositorios a los que envié recientemente, puede configurarlo sorten push.

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

¿Cómo saber si este punto final funciona? Bueno, ¡es hora de intentarlo!

Prueba de puntos finales con curl

Puede enviar una solicitud con cualquier lenguaje de programación. Los usuarios de JavaScript pueden utilizar 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 ; etcétera.

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

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

curl --version

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

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

curl https://api.github.com

Una vez que presiones Enter, deberías recibir una respuesta de Github similar a esta:

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 los caracteres ?y . =Esto se debe a que ?y =son caracteres especiales en la línea de comando. Debes usarlos 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

¡Intente usar cualquiera de los comandos y realice una solicitud! Obtendrá una respuesta similar a la que ha visto con el extremo raíz de Github (pero con muchos más datos).

JSON

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

Un objeto JSON parece 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

Ha aprendido que una solicitud consta de cuatro partes.

1. El punto final
2. El método
3. los encabezados
4. Los datos (o 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ás realizando. Se utilizan para realizar cuatro acciones posibles: , Createy ( CRUD).ReadUpdateDelete

La API le permite saber qué método de solicitud utilizar en cada solicitud. Por ejemplo, para obtener una lista de los repositorios de un usuario, necesita una GETsolicitud: Mejores Opiniones y reviews

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

Puede configurar el método de solicitud en cURL escribiendo -Xo --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

Intente ejecutar esta solicitud. Recibirá una respuesta que le indica que se requiere autenticación. (Más sobre 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 propósitos, como autenticación y proporcionar 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 propiedad-valor separados por dos puntos. El siguiente ejemplo muestra un encabezado que le indica 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 -Ho --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 -vo --verbosemientras envía la solicitud, de esta manera:

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 que se envíe al servidor. Esta opción solo se usa con solicitudes POST, PUTo .PATCHDELETE

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

curl -X POST URL -d property1=value1

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

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 poner en marcha un servidor, puede crear una API y probar sus propios datos. Si no lo sabes, pero te atreves a intentarlo, puedes seguir este artículo para aprender a crear un servidor con Node, Express y MongoDB.

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

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

Ahora, intente enviar algunos datos a su contenedor de solicitudes y 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-Typevalor en application/jsony deberá formatear sus datos como un objeto JSON, como este:

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 bien, ¿recuerda que cuando intentó enviar una POSTsolicitud a través de la API de Github, recibió un mensaje que decía "Requiere autenticación"? Bueno, ¡eso es porque no estás autorizado a realizar la POSTsolicitud!

Autenticación

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

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

En la web, existen dos formas principales de autenticarse:

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

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

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

Para realizar una autenticación básica con cURL, puedes usar la -uopción, seguida de tu 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 solicitudes POST, PUTy ) al servidor.PATCHDELETE

Con el conocimiento que has aprendido hasta ahora, deberías poder editar el código anterior para crear un repositorio de Github a través de tu cURL. ¡Te dejo para 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 recibió anteriormente, como "Requiere autenticación" y "Problemas al analizar JSON", son mensajes de error. Sólo aparecen cuando hay algún problema con su solicitud. Los códigos de estado HTTP le permiten indicar rápidamente el estado de la respuesta. El rango de 100+ a 500+. En general, los números siguen las siguientes reglas:

1. 200+ significa que la solicitud se realizó 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 ( -vo --verbose) o la opción principal ( -Io --head).

Por ejemplo, si intentaste agregar -Iuna POSTsolicitud sin proporcionar tu nombre de usuario y contraseña, obtendrás un código de estado 401 (No autorizado):

Si su solicitud no es válida porque sus datos son incorrectos o faltan, generalmente recibirá 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 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 escribió código para una API anterior, pero su solicitud apunta a la API más nueva.

Puede solicitar una versión 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, utiliza el segundo método. Al momento de escribir este artículo, la API de Github está en la versión 3 y puedes especificar la versión con un Acceptencabezado:

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

Terminando

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

Espero que este artículo te haya ayudado a aprender lo suficiente sobre las API REST y que puedas usarlas con fluidez mientras creas tus aplicaciones. No dudes en visitar mi blog o dejar tus comentarios a continuación si tienes alguna pregunta.

Otras lecturas

• Generación de análisis de sentimiento de audio en tiempo real con IA
• SolidStart: una clase diferente de metamarco
• Consumir API REST en React con Fetch y Axios
• El desarrollo web se está volviendo demasiado complejo y puede ser culpa nuestra

(rb, ra, il, mrn)Explora más en

• API
• API DESCANSO
• javascript

Tal vez te puede interesar:

1. ¿Deberían abrirse los enlaces en ventanas nuevas?
2. 24 excelentes tutoriales de AJAX
3. 70 técnicas nuevas y útiles de AJAX y JavaScript
4. Más de 45 excelentes recursos y repositorios de fragmentos de código

Comprensión y uso de las API REST

¿Qué es una API REST?La anatomía de una solicitudPrueba de puntos finales con curlJSONVolver a la anatomía de una solicitudAutenticaciónCódigos de estado

programar

es

https://aprendeprogramando.es/static/images/programar-comprension-y-uso-de-las-api-rest-925-0.jpg

2025-01-14

Si crees que alguno de los contenidos (texto, imagenes o multimedia) en esta página infringe tus derechos relativos a propiedad intelectual, marcas registradas o cualquier otro de tus derechos, por favor ponte en contacto con nosotros en el mail [email protected] y retiraremos este contenido inmediatamente