Conversaciones Tecnológicas: API REST con JSON

¿Qué es API REST?

REST significa Representational State Transfer (Transferencia de Estado Representacional). Se basa en comunicaciones sin estado, cliente-servidor y almacenables en caché. En la mayoría de los casos, se usa con el protocolo HTTP.

Las aplicaciones RESTful usan las solicitudes HTTP para POSTEAR (crear), PONER (crear y / o actualizar), OBTENER (por ejemplo, realizar consultas) y ELIMINAR datos. REST utiliza HTTP para las cuatro operaciones CRUD (Crear / Leer / Actualizar / Eliminar).

¿Qué es JSON?

JSON (JavaScript Object Notation) es un formato liviano de intercambio de datos. Es fácil para los humanos leer y escribir. Es fácil para las máquinas analizar y generar.

Protocolos

HTTP permite utilizar diferentes protocolos para la comunicación entre el cliente y el servidor. No los explicaremos todos, sino los cuatro más utilizados: GET, PUT, POST y DELETE.

GET, PUT y DELETE deben implementarse como métodos idempotentes. No importa cuántas veces se repitan las solicitudes, el resultado debería ser el mismo. POST, por otro lado, no debe ser idempotente.

GET (OBTENER)
GET lleva a cabo algún tipo de consulta. No solicita ningún cambio en el estado del sistema de ninguna forma o modo. Esto no significa que el servidor no está realizando algún cambio en su estado, pero que el cliente no lo solicitó. Al realizar una solicitud GET, el servidor debe responder con el resultado en forma de JSON.

POST (ENVIAR)
POST es una solicitud para crear una nueva entidad. El contenido de esa entidad debe incluirse en el cuerpo de la solicitud.

PUT (PONER)
PUT es similar a POST con la diferencia de que debe crear una nueva entidad si no existe o modificar la existente.

DELETE (BORRAR)
DELETE es una solicitud para eliminar una entidad especificada del servidor.

Solicitudes al servidor

Evite el uso de no nombres como getAllBooks o createNewBook. El tipo de acción que se realizará se especifica con los métodos HTTP GET, POST, PUT y DELETE. El URI debe especificar la entidad sobre la cual se deben realizar las operaciones. Por ejemplo, GET / books debería recuperar libros del servidor, DELETE / books debería eliminar el libro, PUT / books debería modificar o crear el libro y POST / book debería solicitar la creación del libro en el servidor.

En el caso de un método GET, el resto del URI debe proporcionar información sobre el tipo de servidor de consulta que se debe utilizar para recuperar los datos solicitados. Use parámetros de consulta dentro del URI. Por ejemplo, / books debería devolver todos los libros. / books / id / 24 debe devolver el libro identificado con la ID 24. / books / pageSize / 25 debe devolver solo 25 libros.

El resto de los métodos (POST, PUT y DELETE) deben tener toda la información incluida en el cuerpo del mensaje en el formato JSON.

Del mismo modo que con el método GET, DELETE podría aplicarse a un dato específico, a un subconjunto de datos o a todos ellos (si el servidor lo permite). Si uno quisiera eliminar un libro, DELETE / book request tendría JSON {id: 24} en el cuerpo. Del mismo modo, si uno quisiera eliminar libros que coinciden con algunos criterios más amplios, JSON sería {author: ‘Viktor Farcic’}. Finalmente, si no hay un cuerpo, todos los libros se eliminarán.

POST y PUT funcionan de manera similar a como DELETE. Su cuerpo de solicitud tiene la información que debe ser creada o modificada. Uno podría poner una sola entidad en el cuerpo de la solicitud PUT / books. Esa solicitud crearía o modificaría un solo libro. Un ejemplo podría ser {id: 12345, título: ‘Desarrollo impulsado por el comportamiento’, autor: ‘Viktor Farcic’}. Si se permite la inserción masiva, se pueden pasar varias entidades como una matriz [{título: ‘Desarrollo impulsado por el comportamiento’, autor: ‘Viktor Farcic’}, {título: ‘Integración continua’, autor: ‘Viktor Farcic’}].

Tenga en cuenta que el servidor es responsable de verificar si alguna solicitud está permitida o no. La operación para eliminar más de un libro podría restringirse solo a ciertos usuarios y la solicitud DELETE sin el cuerpo (eliminar todo) puede denegarse para todos los usuarios. La responsabilidad final de decidir si una solicitud está permitida o no está en manos del servidor.

En resumen, GET no tiene el cuerpo y utiliza el URI para especificar la entidad (es decir, / libros) y, cuando sea necesario, parámetros de consulta adicionales (es decir, id / 24). POST, PUT y DELETE no deben especificar parámetros de consulta a través del URI, pero usan el cuerpo del mensaje para pasar la información con respecto a lo que se debe crear, modificar o eliminar.

Respuestas del servidor

Las respuestas del servidor deben ser siempre en formato JSON y consistentes. Siempre deben contener metainformación y, opcionalmente, datos. La consistencia permite a los consumidores de nuestra API saber qué esperar. Además, nos permite escribir menos código de implementación ya que algunos análisis se pueden realizar de forma unificada en todos los tipos de solicitud.

La respuesta HTTP ya contiene el estado (se puede encontrar más información sobre los códigos de estado en Definiciones del código de estado). Podemos mejorar eso con metainformación podría contener información adicional. Se podría proporcionar información adicional específica para la implementación en el servidor con, por ejemplo, error y mensaje. Como regla general, cuando el cliente recibe una respuesta con estado HTTP 2XX, la solicitud fue exitosa. Las respuestas con el estado 4XX representan errores provocados por el cliente (es decir, falta información obligatoria) y 5XX son errores del servidor.

Los datos deben especificarse incluso cuando no se envía ninguno desde el servidor.

Pocos ejemplos serían:

Versiones

Dado que API no será el único punto de entrada para las solicitudes HTTP, a menudo es una buena idea diferenciar los URI de API de los demás. Tiendo a poner prefijos a todos los URI.

Es importante entender que una vez que se publica una API y otros comienzan a usarla, debemos asegurarnos de que los cambios futuros no interrumpan el uso de aquellos que no actualizaron a sus clientes en consecuencia. Por esa razón, es una buena práctica para todos los URI de API con el número de versión. El primero se podría llamar v1, el siguiente v2 y así sucesivamente. De esta forma, tendremos libertad para implementar cambios que potencialmente puedan presentar incompatibilidades como un URI separado.

Con estas dos cosas en mente, nuestro ejemplo anterior con el libro se vería como sigue: / api / v1 / books

Ejemplos
Finalmente, veamos algunos ejemplos con libros.

Solicite la lista de libros
Protocolo: GET
URI: / api / v1 / books
Cuerpo de solicitud: VACÍO
Respuesta:

 

Solicite un solo libro
Protocolo: GET
URI: / api / v1 / books / id / 24
Cuerpo de solicitud: VACÍO
Respuesta:

Solicitar creación de libro
Protocolo: POST
URI: / api / v1 / books
Cuerpo de solicitud:

Solicite que el libro sea creado o modificado
Protocolo: PUT
URI: / api / v1 / books
Cuerpo de solicitud:

Solicitar la eliminación de libros
Protocolo: ELIMINAR
URI: / api / v1 / books
Cuerpo de solicitud:

Fuente: TechnologyConversations