API REST: Requisitos y Ejemplos
El protocolo de transferencia de hipertexto (HTTP) es la vida de la web. Se usa cada vez que transfiere un documento o realiza una solicitud AJAX. Pero HTTP es sorprendentemente un relativo desconocido entre algunos desarrolladores web.
Esta introducción demostrará cómo el conjunto de principios de diseño, conocidos como REST, sustentan a HTTP y le permiten abarcar todo su poder construyendo las API, que se pueden utilizar desde casi cualquier dispositivo o sistema operativo.
¿Por qué REST?
REST es una forma simple de organizar interacciones entre sistemas independientes. Ha estado creciendo en popularidad desde 2005 e inspira el diseño de servicios, como la API de Twitter.
Esto se debe al hecho de que REST le permite interactuar con una sobrecarga mínima con clientes tan diversos como teléfonos móviles y otros sitios web. En teoría, REST no está vinculado a la web, pero casi siempre se implementa como tal y se inspiró en HTTP. Como resultado, REST puede usarse donde sea que HTTP pueda.
La alternativa es construir convenciones relativamente complejas sobre HTTP. A menudo, esto toma la forma de nuevos lenguajes basados en XML. El ejemplo más ilustre es SOAP. Tienes que aprender un conjunto de convenciones completamente nuevo, pero nunca usar HTTP en toda su potencia. Debido a que REST se ha inspirado en HTTP y juega con sus puntos fuertes, es la mejor manera de aprender cómo funciona HTTP.
¿Cómo se usa una API REST?
Una API REST define un conjunto de funciones que los desarrolladores pueden realizar solicitudes y recibir respuestas a través del protocolo HTTP, como GET y POST.
Debido a que la API REST usa HTTP, pueden ser utilizados por prácticamente cualquier lenguaje de programación y son fáciles de probar (es un requisito de una API REST que el cliente y el servidor sean independientes entre sí, lo que permite codificarlo en cualquier idioma y mejorar al soportar la longevidad y evolución).
Un ejemplo del mundo real
Twitter proporciona una API REST que puede consultar para obtener los últimos tweets, puede proporcionar una consulta de búsqueda (o una etiqueta hash) y devolverá los resultados en formato JSON. Ejemplo de esta solicitud HTTP a la API de Twitter para obtener los últimos 3 tweets que coinciden con "jQuery".
http://search.twitter.com/search.json?q=jQuery&result_type=recent&rpp=3
Requisitos clave para una API REST
- Debe usar estándares web donde tengan sentido
- Debe ser amigable para el desarrollador y ser explorable a través de una barra de direcciones del navegador
- Debe ser simple, intuitivo y consistente para hacer que la adopción no solo sea fácil sino también agradable
- Debe proporcionar suficiente flexibilidad para impulsar la mayoría de la interfaz de usuario de encantamiento.
- Debe ser eficiente, manteniendo el equilibrio con los otros requisitos
Una API es la interfaz de usuario de un desarrollador: al igual que cualquier UI, es importante asegurarse de que la experiencia del usuario se piense cuidadosamente.
Use URLs y acciones RESTful
Si hay una cosa que ha ganado amplia adopción, son los principios RESTful.
Estos fueron presentados por primera vez por Roy Fielding en el Capítulo 5 de su disertación sobre arquitecturas de software basadas en red.
Los principios clave de REST implican separar su API en recursos lógicos. Estos recursos se manipulan utilizando solicitudes HTTP donde el método (GET, POST, PUT, PATCH, DELETE) tiene un significado específico.
Una vez que haya definido sus recursos, debe identificar qué acciones se aplican a ellos y cómo se correlacionarían con su API. Los principios RESTful proporcionan estrategias para manejar las acciones CRUD utilizando los métodos HTTP mapeados de la siguiente manera:
Ejemplo
GET / tickets: recupera una lista de tickets
GET / tickets / 12 - Recupera un ticket específico
POST / tickets: crea un nuevo ticket
PUT / tickets / 12 - Actualiza ticket # 12
PATCH / tickets / 12 - Actualiza parcialmente el ticket # 12
DELETE / tickets / 12 - Elimina el ticket # 12
Lo mejor de REST es que aprovecha los métodos HTTP existentes para implementar funcionalidades significativas en solo un punto final de tickets. No hay convenciones de nombres de métodos a seguir y la estructura de URL es clara.
Cómo diseñar una API REST
Conocer lo que es REST es una cosa, mientras que la aplicación de sus conceptos en el diseño de aplicaciones reales es completamente otro desafío. En esta sección mostraremos como diseñar una API REST para una aplicación basada en red.
Identificar el modelo de objeto
El primer paso para diseñar una aplicación basada en REST API es: identificar los objetos que se presentarán como recursos.
Para una aplicación basada en la red, el modelado de objetos es bastante más simple. Puede haber muchas cosas, como dispositivos, entidades gestionadas, enrutadores, módems, etc. Por razones de simplicidad, consideraremos solo dos recursos.
- Dispositivos
- Configuraciones
Aquí la configuración es sub-recurso de un dispositivo. Un dispositivo puede tener muchas opciones de configuración.
Tenga en cuenta que ambos objetos / recursos en nuestro modelo anterior tendrán un identificador único, que es la propiedad de identificación.
Crear un modelo URI
Ahora que el modelo de objetos está listo, es hora de decidir los URI de los recursos. En este paso, mientras diseña los URI de los recursos, céntrese en la relación entre los recursos y sus sub-recursos. Estas URI de recursos son puntos finales para los servicios RESTful.
En nuestra aplicación, un dispositivo es un recurso de nivel superior. Y la configuración es un sub-recurso en el dispositivo. Anotemos las URIs.
/dispositivos
/dispositivos/{id}
/configuraciones
/configuraciones/{id}
/dispositivos/{id}/configuraciones
/dispositivos/{id}/configuraciones/{id}
Tenga en cuenta que estas URI no utilizan ningún verbo u operación. Es muy importante no incluir verbos en las URI. Las URI deben ser solo nombres.
Determinar representaciones
Ahora, cuando se han decidido las URI de recursos, trabajemos en sus representaciones. La mayoría de las representaciones se definen en formato XML o JSON. En la sección de ejemplos de apis puedes ver algunas representaciones.