Levi Velázquez

Introducción al diseño de una API REST

Qué es y cómo diseñar un API REST siguiendo los principios básicos

Primero, debemos saber el significado de API, por sus siglas en inglés Application Programming Interface. Básicamente, representan una colección de métodos y funciones implementadas en un sistema con el fin de que las mismas sean utilizadas por otros.

A medida que surgieron APIs sobre aplicaciones y plataformas web, se fue formando el término API REST, el cual se usa para denominar a las API que están implementadas bajo el protocolo HTTP. En otras palabras, un API REST permite el uso de un servicio(función o método) perteneciente a una plataforma a un usuario externo para que el mismo lo use en una aplicación propia. Puede ocurrir el caso que ese usuario externo también seamos nosotros mismos.

Características

URI’s para identificación de recursos

Un recurso básicamente representa una sección, archivo o contenido que deseamos obtener o modificar de una plataforma web a través de su API REST. Los mismos serán identificados por una URI, la cuál nos ayudará a obtener/modificar el mismo.

Las URI’s deben cumplir con ciertas características:

• No deben llevar un verbo que implique una acción
  Incorrecto: /recursos/id/editar
  Correcto: /recursos/id/

• Deben identificar solo a un recurso, deben ser únicas.

• No deben tomar en cuenta el formato en la construcción de la URI
  Incorrecto: /recursos/archivo.pdf
  Correcto: /recursos/archivo

• Deben mantener una jerarquía lógica.
  Incorrecto: /apartamentos/2/edificio/3
  Correcto: /edificios/3/apartamentos/2

• Los filtrados de información deben hacerse mediante los parámetros HTTP
  Incorrecto: /edificios/3/apartamentos/2/orden/asc
  Correcto: /edificios/3/apartamentos/2/?orden=asc

• Deben especificarse usando su forma plural
  Incorrecto: /apartamento/2/
  Correcto: /apartamentos/2/

Semántica de los métodos HTTP (GET, POST, PUT, PATCH, DELETE)

Una vez conocidas las principales reglas a la hora de construir nuestras URIs, pasamos al siguiente paso, darle un significado semántico o de acción a los métodos HTTP. Ampliando nuestro camino un poco más allá de los dos métodos más utilizados comúnmente: GET y POST.

Los métodos serían los siguientes:

• GET: Para consultar y leer recursos
• POST: Para crear recursos
• PUT: Para editar recursos
• DELETE: Para eliminar recursos.
• PATCH: Para editar partes concretas de un recurso.

Resultado final

Uniendo los dos puntos anteriormente explicados, tendremos como resultado las principales reglas que debemos tomar en cuenta a la hora de diseñar las URL’s para nuestra API REST.

GET /series Nos permite acceder al listado de series.

POST /series Nos permite crear una nueva serie.

GET /series/123 Nos permite acceder al detalle de una serie.

PUT /series/123 Nos permite editar una serie, sustituyendo la totalidad de la información anterior por la nueva.

DELETE /series/123 Nos permite eliminar una serie.

PATCH /series/123 Nos permite modificar parcialmente la información de una serie, como el nombre.

Con esto hemos establecido los principios fundamentales para construir un API REST siguiendo los estándares establecidos. Todavía quedan muchas consideraciones que tomar a la hora de diseñar un API REST. Las mismas las estaré tocando en otro post un poco más extenso.

En el próximo tutorial, comenzaremos a hacer nuestra primera API REST usando Django y Django Rest Framework.

Ahora un gif porque los gif son cheveres.

When nobody notices my bug during the demo

Si les pareció útil el post, ayudanos a compartirlo.