El diseño de una API RESTful efectiva y eficiente requiere seguir ciertas buenas prácticas que aseguren su usabilidad, mantenibilidad y escalabilidad. A continuación, se detallan algunas de las mejores prácticas que se deben considerar al diseñar APIs RESTful.

• Nombres de recursos: Deben ser sustantivos y representar entidades del sistema.
• Consistencia: Mantener un esquema de nomenclatura uniforme.

• Correcto: /users, /orders, /products
• Incorrecto: /getUsers, /createOrder, /productList

Define los nombres de recursos para una API de biblioteca que maneje libros, autores y géneros.

Solución:

• /books
• /authors
• /genres

• GET: Recuperar recursos.
• POST: Crear nuevos recursos.
• PUT: Actualizar recursos existentes.
• DELETE: Eliminar recursos.

• GET /users: Obtener una lista de usuarios.
• POST /users: Crear un nuevo usuario.
• PUT /users/{id}: Actualizar un usuario existente.
• DELETE /users/{id}: Eliminar un usuario.

Asigna el método HTTP correcto para las siguientes operaciones:

1. Obtener detalles de un libro.
2. Añadir un nuevo autor.
3. Actualizar información de un género.
4. Eliminar un libro.

Solución:

1. GET /books/{id}
2. POST /authors
3. PUT /genres/{id}
4. DELETE /books/{id}

• 2xx: Éxito (200 OK, 201 Created).
• 4xx: Error del cliente (400 Bad Request, 404 Not Found).
• 5xx: Error del servidor (500 Internal Server Error).

• 200 OK: Solicitud exitosa.
• 201 Created: Recurso creado exitosamente.
• 400 Bad Request: Solicitud malformada.
• 404 Not Found: Recurso no encontrado.

¿Qué código de estado HTTP devolverías en las siguientes situaciones?

1. Un usuario intenta acceder a un recurso que no existe.
2. Una solicitud para crear un nuevo recurso es exitosa.
3. El servidor encuentra un error inesperado.

Solución:

1. 404 Not Found
2. 201 Created
3. 500 Internal Server Error

• Versionado en la URL: Incluir la versión en la ruta del endpoint.
• Versionado en el encabezado: Incluir la versión en los encabezados HTTP.

• Versionado en la URL: /v1/users, /v2/users
• Versionado en el encabezado: Accept: application/vnd.myapi.v1+json

¿Cómo versionarías una API que tiene endpoints para manejar libros y autores?

Solución:

• En la URL: /v1/books, /v1/authors
• En el encabezado: Accept: application/vnd.libraryapi.v1+json

• Descripción de endpoints: Detallar cada endpoint y su propósito.
• Ejemplos de solicitudes y respuestas: Proveer ejemplos claros.
• Especificaciones de parámetros: Describir todos los parámetros requeridos y opcionales.

• Swagger: Herramienta popular para documentar APIs.
• Postman: Puede ser utilizado para generar documentación.

Documenta un endpoint para obtener la lista de libros, incluyendo la descripción, método HTTP, parámetros y ejemplos de solicitud y respuesta.

Solución:

• Descripción: Obtener una lista de todos los libros disponibles.
• Método HTTP: GET
• Endpoint: /books
• Parámetros: Ninguno
• Ejemplo de solicitud:

  GET /books HTTP/1.1
  Host: api.library.com
  

• Ejemplo de respuesta:

  [
    {
      "id": 1,
      "title": "1984",
      "author": "George Orwell",
      "genre": "Dystopian"
    },
    {
      "id": 2,
      "title": "To Kill a Mockingbird",
      "author": "Harper Lee",
      "genre": "Fiction"
    }
  ]
  

En esta sección, hemos cubierto algunas de las mejores prácticas esenciales para el diseño de APIs RESTful, incluyendo el uso de nombres de recursos claros, métodos HTTP adecuados, códigos de estado HTTP apropiados, versionado de APIs y la importancia de una documentación clara y completa. Siguiendo estas prácticas, podrás diseñar APIs que sean fáciles de usar, mantener y escalar. En el próximo módulo, profundizaremos en la seguridad de las APIs RESTful.