Scribd
Cargar
4 vistas19 páginas

Resful API

El documento detalla los principios y mejores prácticas para el diseño de APIs RESTful, enfocándose en la correcta estructuración de URIs y el uso de métodos HTTP. Se enfatiza la importancia de utilizar sustantivos en las URLs, evitar la anidación excesiva y asegurar que las respuestas de la API estén en formato JSON con códigos de estado HTTP adecuados. Además, se presentan ejemplos de buenas y malas prácticas en el diseño de URIs y manejo de respuestas.

Cargado por

Luis Antonio Gutiérrez Rodas
Derechos de autor
© © All Rights Reserved
Nos tomamos en serio los derechos de los contenidos. Si sospechas que se trata de tu contenido, reclámalo aquí.
Formatos disponibles
Descarga como PDF, TXT o lee en línea desde Scribd
4 vistas19 páginas

Resful API

El documento detalla los principios y mejores prácticas para el diseño de APIs RESTful, enfocándose en la correcta estructuración de URIs y el uso de métodos HTTP. Se enfatiza la importancia de utilizar sustantivos en las URLs, evitar la anidación excesiva y asegurar que las respuestas de la API estén en formato JSON con códigos de estado HTTP adecuados. Además, se presentan ejemplos de buenas y malas prácticas en el diseño de URIs y manejo de respuestas.

Cargado por

Luis Antonio Gutiérrez Rodas
Derechos de autor
© © All Rights Reserved
Nos tomamos en serio los derechos de los contenidos. Si sospechas que se trata de tu contenido, reclámalo aquí.
Formatos disponibles
Descarga como PDF, TXT o lee en línea desde Scribd
Está en la página 1/ 19

01/19

RESTful API:
Principios, Diseño y
Mejores Practicas

Tomás Cuevas
@tomás-cuevas-dev
Diseño de URI 02/19

Diseño de URI:
En el diseño de una API RESTful, las URLs
representan generalmente recursos
(objetos), mientras que los métodos HTTP
(como GET, POST, PUT, DELETE, etc.) indican
las operaciones que se pueden realizar
sobre ellos.

Este enfoque se centra en el estado y la


representación de los recursos, en lugar de
enfocarse en las acciones.

Tomás Cuevas
@tomás-cuevas-dev
Diseño de URI 03/19

Verbo + Objeto
Los verbos en una API RESTful
corresponden a los cinco principales
métodos HTTP, alineados con las
operaciones CRUD:

- GET: Obtener
- POST: Crear
- PUT: Actualizar
- PATCH: Modificar parcialmente
- DELETE: Eliminar

Según la especificación HTTP, los verbos


deben escribirse siempre en mayúsculas.

Tomás Cuevas
@tomás-cuevas-dev
Diseño de URI 04/19

El Objeto Debe Ser


un Sustantivo
Al diseñar una API, la URL debe representar
un recurso, que actúa como el objeto del
verbo HTTP utilizado.

Siguiendo los principios del diseño RESTful,


las URLs deben utilizar sustantivos en lugar
de verbos, ya que representan una
colección de recursos o una instancia
única, y no una acción.

Tomás Cuevas
@tomás-cuevas-dev
Diseño de URI 05/19

Ejemplos Incorrectos:
❌ /getAllCars
❌ /createNewCar
❌ /deleteAllRedCars
Estos ejemplos contienen verbos (get,
create, delete), lo que indica acciones en
lugar de recursos, lo que no cumple con las
normas semánticas de RESTful.

Tomás Cuevas
@tomás-cuevas-dev
Diseño de URI 06/19

Ejemplos Correctos:
✅ /cars → Representa una colección de
autos.

✅ /cars/{id} → Hace referencia a un auto en


particular.

✅ /cars/{id}/color → Representa el color de un


auto específico.

De esta forma, la estructura RESTful se


mantiene clara, intuitiva y alineada con los
estándares de la arquitectura.

Tomás Cuevas
@tomás-cuevas-dev
Diseño de URI 07/19

URLs en Plural
Se recomienda utilizar nombres en plural en
las URLs para mantener la consistencia y
claridad, ya que normalmente representan
colecciones de recursos.

Tomás Cuevas
@tomás-cuevas-dev
Diseño de URI 08/19

Convención de Pluralidad en URLs:


✅ /users → Representa una colección de
usuarios.
❌ /user → No es recomendable, ya que
sugiere un solo usuario en lugar de un
conjunto.

Incluso al hacer referencia a un recurso


individual, se mantiene el plural para
conservar la uniformidad:

✅ /users/123 → Representa un usuario


específico con ID 123.

Tomás Cuevas
@tomás-cuevas-dev
Diseño de URI 09/19

Relaciones Jerárquicas en URLs:


Cuando los recursos tienen una relación
jerárquica, la URL debe reflejar esta
estructura:

✅ /users/123/posts → Representa la
colección de publicaciones del usuario con
ID 123.

Este enfoque mantiene las rutas coherentes,


estructuradas y fáciles de entender dentro
del diseño RESTful.

Tomás Cuevas
@tomás-cuevas-dev
Diseño de URI 10/19

Evitar URLs
Profundamente
Anidadas
Un problema común en el diseño de APIs
RESTful es la anidación excesiva de URLs
cuando se necesita clasificar los recursos en
múltiples niveles. Esto dificulta la
escalabilidad, la extensibilidad y la
comprensión de la API.

Tomás Cuevas
@tomás-cuevas-dev
Diseño de URI 11/19

Ejemplo de URL con anidación excesiva:


❌ GET /authors/12/categories/2
Esta estructura es difícil de extender y puede
generar confusión.

Enfoque recomendado con parámetros


de consulta:
✅ GET /authors/12?categories=2
Este método simplifica la estructura y
permite una mayor flexibilidad en las
consultas.

Tomás Cuevas
@tomás-cuevas-dev
Diseño de URI 12/19

Otro caso común es la consulta de artículos


publicados:

❌ GET /articles/published
✅ GET /articles?published=true
El uso de query parameters mantiene las
URLs más limpias, mejora la claridad
semántica y permite realizar consultas más
dinámicas sin modificar la estructura base de
la API.

Tomás Cuevas
@tomás-cuevas-dev
Respuestas de una API 13/19

Respuestas de una
API
Las respuestas de una API deben estar en
formato JSON estructurado, no en texto
plano, para mantener un formato estándar y
facilitar la interoperabilidad.

El servidor debe establecer el encabezado


Content-Type como application/json y el
cliente debe especificar que acepta
respuestas JSON mediante el encabezado
Accept en la solicitud:

Tomás Cuevas
@tomás-cuevas-dev
Respuestas de una API 14/19

Tomás Cuevas
@tomás-cuevas-dev
Respuestas de una API 15/19

No Retornar
Código 200 en
Caso de Error
Un error común es devolver 200 OK incluso
cuando ocurre un fallo, incluyendo los
detalles del error dentro del cuerpo de la
respuesta.

Esto obliga al cliente a analizar el body en


lugar de depender del código de estado
HTTP, lo que complica la detección de
errores.

Tomás Cuevas
@tomás-cuevas-dev
Respuestas de una API 16/19

❌ Ejemplo incorrecto:

En este caso, la solicitud falló, pero el


servidor sigue devolviendo 200 OK, lo que no
es una práctica RESTful adecuada.

Tomás Cuevas
@tomás-cuevas-dev
Respuestas de una API 17/19

✅ Ejemplo con código adecuado (404


Not Found):

El código de estado HTTP debe reflejar con


precisión el resultado de la solicitud,
mientras que el cuerpo de la respuesta debe
proporcionar información detallada sobre el
error. Aquí, el código 404 indica claramente
que el recurso no fue encontrado.

Tomás Cuevas
@tomás-cuevas-dev
Respuestas de una API 18/19

✅ Ejemplo con código adecuado (422


Unprocessable Entity):

En este caso, el código 422 indica que la


solicitud contiene errores de validación,
proporcionando detalles específicos sobre
los campos incorrectos.

Tomás Cuevas
@tomás-cuevas-dev
19/19

¿Te fue útil esta


publicación?
¡DÉJAMELO EN LOS
COMENTARIOS!
Tomás Cuevas
@tomás-cuevas-dev 📩🔥

También podría gustarte