Como construir una API RESTful - Guía paso a paso

En este artículo, voy a hablar sobre cómo diseñar mejor sus APIs RESTful para evitar errores comunes

Como desarrolladores de software, la mayoría de nosotros usamos o construimos APIs de REST en el día a día. Las API son el medio de comunicación por defecto entre los sistemas. Amazon es el mejor ejemplo de cómo las APIs pueden ser utilizadas eficientemente para la comunicación.

Mandato de Jeff Bezos (Clave del éxito)

Algunos de ustedes ya conocían el mandato de Jeff Bezos a los desarrolladores de Amazon. Si nunca tuviste la oportunidad de escucharlo, los siguientes puntos son el quid de la cuestión.

• A partir de ahora, todos los equipos expondrán sus datos y funcionalidad a través de interfaces de servicio.
• Los equipos deben comunicarse entre sí a través de estas interfaces.
• No se permitirá ninguna otra forma de comunicación interprocesal, ni enlaces directos, ni lecturas directas del BBDD de otro equipo, ni modelos de memoria compartida, ni puertas traseras de ningún tipo. La única comunicación permitida es a través de llamadas de interfaz de servicio a través de la red.
• No importa qué tecnología usen. HTTP, Corba, Pubsub, protocolos personalizados - no importa. A Bezos no le importa.
• Todas las interfaces de servicio, sin excepción, deben ser diseñadas desde cero para poder ser externalizadas. Es decir, el equipo debe planificar y diseñar para poder exponer la interfaz a los desarrolladores del mundo exterior. Sin excepciones.
• Cualquiera que no haga esto será despedido.

Principios de diseño de APIs RESTful

Ahora vamos a entender los principios que debemos seguir al diseñar las APIs de RESTful.

Manténgalo simple (Keep it simple)

Necesitamos asegurarnos de que la URL base de la API sea simple. Por ejemplo, si queremos diseñar APIs para productos, debería diseñarse como:

/products

/products/12345
      

La primera API es para obtener todos los productos y la segunda es para obtener un producto específico.

Usar sustantivos y no verbos

Muchos desarrolladores cometen este error. Generalmente olvidan que tenemos métodos HTTP para describir mejor las APIs y terminan usando verbos en las URLs de las APIs. Por ejemplo, API para obtener todos los productos debe ser:

/products
      

y no como se muestra a continuación

/getAllProducts
      

Algunos patrones de URL comunes, que he visto hasta ahora.

Uso de los métodos HTTP adecuados

Las APIs de RESTful tienen varios métodos para indicar el tipo de operación que vamos a realizar con esta API.

• GET — Para obtener un recurso o colección de recursos.
• POST — Para crear un recurso o colección de recursos.
• PUT/PATCH — Para actualizar el recurso o conjunto de recursos existentes.
• DELETE — Para borrar el recurso existente o el conjunto de recursos.

Necesitamos asegurarnos de que usamos el método HTTP correcto para una operación determinada.

Usar plurales

Este tema es un poco discutible. A algunas personas les gusta mantener el URL del recurso con nombres plurales mientras que a otras les gusta mantenerlo en singular. Por ejemplo —

/products/product
    

Me gusta mantenerlo en plural ya que evita confusiones sobre si estamos hablando de obtener un solo recurso o una colección. También evita añadir cosas adicionales como adjuntar todo a la URL base, por ejemplo /product/all

Puede que a algunas personas no les guste esto, pero mi única sugerencia es mantenerlo uniforme en todo el proyecto.

Utilizar parámetros

A veces necesitamos tener una API que debería contar más que sólo por identificación. Aquí debemos hacer uso de los parámetros de consulta para diseñar la API.

• /products?name=’ABC’ debe ser preferido sobre /getProductsByName
• /products?type=’xyz’ debe ser preferido sobre /getProductsByType

De esta manera puede evitar URLs largas con simplicidad en el diseño.

Utilice códigos HTTP adecuados

Tenemos muchos códigos HTTP. La mayoría de nosotros sólo terminamos usando dos - 200 y 500! Esta no es, desde luego, una buena práctica. A continuación se presentan algunos de los códigos HTTP más utilizados.

• 200 OK — Este es el código HTTP más comúnmente utilizado para mostrar que la operación realizada es exitosa.
• 201 CREATED — Esto se puede utilizar cuando utiliza el método POST para crear un nuevo recurso.
• 202 ACCEPTED — Esto se puede utilizar para confirmar la petición enviada al servidor.
• 400 BAD REQUEST — Esto se puede utilizar cuando falla la validación de entrada del lado del cliente.
• 401 UNAUTHORIZED / 403 FORBIDDEN— Esto se puede utilizar si el usuario o el sistema no está autorizado para realizar una determinada operación.
• 404 NOT FOUND— Esto se puede utilizar si está buscando un recurso determinado y no está disponible en el sistema.
• 500 INTERNAL SERVER ERROR — Esto nunca debe ser lanzado explícitamente, pero puede ocurrir si el sistema falla.
• 502 BAD GATEWAY — Esto se puede utilizar si el servidor ha recibido una respuesta no válida del servidor ascendente.

Versiones

La creación de versiones de las API es muy importante. Muchas empresas diferentes utilizan las versiones de diferentes maneras. Algunas utilizan versiones como fechas, mientras que otras utilizan versiones como parámetros de consulta. Generalmente me gusta mantenerlo prefijado al recurso. Por ejemplo:

/v1/products

/v2/products
    

También me gustaría evitar el uso de /v1.2/products, ya que implica que la API cambiaría con frecuencia. Además, los puntos (.) pueden no ser fácilmente visibles en las URL. Así que hazlo simple.

Siempre es una buena práctica mantener la compatibilidad hacia atrás para que si cambia la versión de la API, los consumidores tengan suficiente tiempo para pasar a la siguiente versión.

Usar paginación

El uso de la paginación es imprescindible cuando se expone una API que puede devolver grandes cantidades de datos, y si no se hace un balanceo de carga adecuado, el consumidor puede terminar por derribar el servicio. Debemos tener siempre en mente que el diseño de la API debe ser a prueba de tontos y a prueba de tontos.

Uso de limit y offset se recomienda aquí. Por ejemplo, /products?limit=25&offset=50. También se aconseja mantener un valor predeterminado de limit y offset.

Formatos soportados

También es importante elegir cómo responderá su API. La mayoría de las aplicaciones de hoy en día deberían devolver las respuestas de JSON, a menos que tenga una aplicación heredada que aún necesite obtener una respuesta XML.

Utilizar mensajes de error adecuados

Siempre es una buena práctica mantener un conjunto de mensajes de error que la aplicación envía y responder a ellos con la identificación adecuada. Por ejemplo, si utilizas APIs de gráficos de Facebook, en caso de errores, devuelve un mensaje como este:

{

  "error": {

    "message": "(#803) Some of the aliases you requested do not exist: products",

    "type": "OAuthException",

    "code": 803,

    "fbtrace_id": "FOXX2AhLh80"  }

}
    

También he visto algunos ejemplos en los que la gente devuelve una URL con un mensaje de error, que le dice más sobre el mensaje de error y cómo manejarlo también.

Uso de las especificaciones de OpenAPI

Con el fin de que todos los equipos de su empresa se atengan a ciertos principios, el uso de OpenAPI specification puede ser útil. OpenAPI le permite diseñar primero sus APIs y compartirlas con los consumidores de una manera más fácil.

Conclusiones

Es bastante evidente que si desea comunicarse mejor, las APIs son el camino a seguir. Pero si están mal diseñados, puede aumentar la confusión. Así que ponga su mejor esfuerzo en diseñar bien, y el resto es sólo la implementación.

Gracias por leer ❤

Luigi Nori

He has been working on the Internet since 1994 (practically a mummy), specializing in Web technologies makes his customers happy by juggling large scale and high availability applications, php and js frameworks, web design, data exchange, security, e-commerce, database and server administration, ethical hacking. He happily lives with @salvietta150x40, in his (little) free time he tries to tame a little wild dwarf with a passion for stars.