Lo Básico de REST y RESTful API Development

Los desarrolladores web suelen hablar sobre los principios de REST y la arquitectura de datos RESTful, ya que es un aspecto crucial del desarrollo moderno, pero a veces puede ser increíblemente confuso. REST no es una tecnología en sí misma, sino más bien un método para crear API con ciertos principios de organización . Estos principios son para guiar a los desarrolladores y crear un entorno más universal para procesar las solicitudes API.

En este post, me gustaría explicar las prácticas de desarrollo RESTful a vista de pájaro. Quiero abordar el qué en lugar del cómo . Aunque me referiré a ambas áreas, esta publicación está hecha para cualquiera que esté interesado en el desarrollo web, pero simplemente no puede entender el concepto de API REST.

RESTO para desarrolladores web

El acrónimo REST significa Representational State Transfer . Esto puede sonar algo confuso, y la entrada de la wiki lo hace sonar aún más confuso. Pero es posible simplificar la terminología.

REST es solo una serie de pautas y estilos arquitectónicos utilizados para la transmisión de datos . Se aplica comúnmente a aplicaciones web, pero también puede pasar datos al software.

El acrónimo API significa Application Programming Interface, que son métodos de conexión con otras bibliotecas o aplicaciones . Windows tiene múltiples API, y Twitter también tiene una API web, aunque realizan diferentes tareas con diferentes objetivos.

Combinando todo junto, las API RESTful son API que siguen la arquitectura REST.

¿Qué es exactamente la arquitectura REST?

Aquí es donde es difícil establecer detalles. Sin embargo, hay algunas constantes arquitectónicas, tales como:

• Consistencia en toda la API
• Existencia sin estado, es decir, sin sesiones en el servidor
• Uso de códigos de estado HTTP cuando corresponda
• Uso de puntos finales de URL con una jerarquía lógica
• Versiones en la URL en lugar de en encabezados HTTP

No existen pautas demasiado específicas como la especificación W3C HTML5 que podría generar confusión y un miasma de incertidumbre en torno a la terminología REST.

Además, la lista anterior no debe considerarse reglas rígidas, a pesar de que son ciertas para la mayoría de las API RESTful modernas.

REST es una metodología liviana que lo hace perfecto para datos HTTP. Esta es la razón por la que REST se hizo tan popular en la web, y por qué es ampliamente considerada como la mejor opción para el desarrollo de API.

Como dice Vinay Sahni, "una API es la interfaz de usuario de un desarrollador". Todo debería ser fácil de usar y proporcionar una excelente experiencia de usuario. Las API RESTful apuntan a hacer justamente eso.

Puntos clave para API RESTful

Estos consejos están en el contexto de las API estrictamente para aplicaciones web . Esto significa que HTTP es un requisito y, a menudo, significa que los datos de la API se alojan en un servidor externo . Examinemos cómo funcionan las API RESTful del lado del usuario API.

El usuario API es el desarrollador web que puede construir una secuencia de comandos que se conecta a un servidor API externo, luego los datos necesarios se pasan a través de HTTP. El desarrollador puede mostrar datos en su sitio web sin tener acceso personal al servidor externo (como extraer datos de Twitter).

En general, hay cuatro comandos utilizados para acceder a las API RESTful :

1. GET para recuperar un objeto
2. POST para crear un nuevo objeto
3. PUT para modificar o reemplazar un objeto
4. DELETE para eliminar un objeto

Cada uno de estos métodos se debe pasar con la llamada API para indicarle al servidor qué hacer.

La gran mayoría de las API web solo permiten solicitudes GET para extraer datos de un servidor externo. La autenticación es opcional, pero ciertamente es una buena idea cuando se permiten comandos potencialmente dañinos como PUT o DELETE .

Sin embargo, no muchas API RESTful incluso llegan tan lejos. Considere Pokéapi, que es una base de datos API de Pokémon gratuita. Está abierto al público con un límite de frecuencia decente (lo que limita a los usuarios a un cierto número de solicitudes de API durante un período de tiempo), pero solo permite el método GET para acceder a los recursos. Esto se puede denominar coloquialmente una API solo de consumo .

Los tipos de devolución también son importantes y deben mantener la homogeneidad para todos los recursos. JSON es un tipo de devolución popular con especificaciones en línea que explican las estructuras de datos adecuadas.

Las API RESTful usan sustantivos para objetos API y verbos para realizar acciones en esos objetos. La autenticación puede ser parte de esto, la limitación de velocidad también puede ser parte de esto. Pero una API muy simple puede funcionar sin preocuparse por las limitaciones del usuario.

Acceder a los recursos de la API

Las API públicas suelen ser accesibles desde direcciones web directas . Esto significa que la estructura de la URL es importante y debe usarse solo para las solicitudes de la API.

Algunas URL pueden incluir un directorio de prefijos como /v2/ para una versión actualizada 2 de una API anterior. Esto es común para los desarrolladores que no desean depreciar su API 1.x, pero aún desean ofrecer la estructura más nueva.

Realmente disfruté esta publicación que cubre estructuras de URL básicas y ejemplos de otros servicios.

Tenga en cuenta que los datos de retorno del punto final cambiarán drásticamente en función del método HTTP . Por ejemplo, GET recupera contenido, mientras que POST crea contenido nuevo. La solicitud podría apuntar al mismo punto final, pero el resultado podría ser muy diferente.

Consultar ejemplos en línea puede ayudarlo a comprender conceptos más claros. Ya vimos Pokeapi, pero aquí hay algunos ejemplos de la API del mundo real para examinar:

• Reddit API
• API de GitHub
• API de Flickr
• API de Pinterest

Crea tu propia API

El proceso de construir tu propia API no debe tomarse a la ligera, pero tampoco es tan complicado como podrías pensar. Comprende los patrones de diseño de API y las mejores prácticas para construir algo de valor real.

Cada API debe conectarse a su servidor para devolver datos de algún tipo. No solo necesita escribir código para hacerlo, sino que también necesita formatear los datos de retorno. Otros requisitos potenciales incluyen la autenticación y la limitación de velocidad, por lo que construir una API ciertamente no es para los débiles.

Pero echemos un vistazo a algunos principios básicos de la arquitectura API.

Construir puntos finales

Un aspecto del desarrollo de API es la construcción de puntos finales . Al crear recursos, debe usar sustantivos, no verbos. Esto significa que los datos de la API deben devolver una persona, lugar o cosa, la mayoría de las veces es una cosa con atributos específicos (por ejemplo, un tweet y todos sus metadatos).

Puede ser difícil aprender a nombrar nombres, pero este es un aspecto crucial del desarrollo de API. La simplificación es mejor siempre que sea posible.

Un gran debate es singular vs. sustantivo plural . Si estuvieras haciendo una API de Twitter, podrías tener el grupo de objetos primero (es decir, twittear), luego el segundo elemento de objeto (es decir, ID de tweet).

 $ / tweet / 15032934882934 $ / tweets / 15032934882934 

En este caso, yo diría que la forma singular se ve mejor. Esto es cierto especialmente cuando solo se devuelve un recurso. Pero no hay una respuesta documentada al 100% correcta, así que haga lo que mejor se adapte a su proyecto.

Establecer el tipo de devolución

Otra consideración son los datos del tipo de devolución . La mayoría de los usuarios de la web esperan contenido JSON, por lo que es la mejor opción. XML es otra opción si desea ofrecer ambos. Sin embargo, JSON es el tipo de retorno API fundamental entre los desarrolladores web.

El desarrollo de API implica mucho más, por lo que recomiendo jugar primero con las API. De esta forma, puede ver cómo otros desarrolladores crean sus API, y con suerte se familiarizará con los requisitos típicos.

Si recién está comenzando, considere considerar estos tutoriales de desarrollo:

• REST API Tutorial Site
• Escribir una API REST simple
• Construyendo un servicio web RESTful

Recursos adicionales

La mejor forma de aprender el desarrollo de aplicaciones web es a través de la práctica. La teoría otorgada siempre vale la pena estudiarla, porque te permite conversar con los desarrolladores y comprender cómo funcionan las cosas.

Pero un buen lugar para comenzar con el desarrollo de API es conectarse primero a otras API . Aprenda los conceptos básicos de las conexiones del lado del cliente, y desde allí puede pasar al desarrollo de API del lado del servidor creando su propia API desde cero.

Si ese es su objetivo, considere los siguientes recursos para ayudarlo en su viaje.

Libros

• REST API Design Rulebook
• API web RESTful
• RESTful Web Services Cookbook
• RESTO indistinto: una guía para diseñar la API perfecta

Artículos

• Una guía para principiantes sobre HTTP y REST
• Creando una API RESTful
• Guía de nombres de recursos RESTful
• Crear una API REST usando la pila MEAN