Documentación de API REST con editor de texto

Domina cómo documentar una API REST solo con un editor de texto: desde definir recursos y endpoints hasta detallar verbos HTTP, headers, body en JSON y status codes. Aquí verás una guía práctica para una API de productos, clara y lista para compartir.

¿Cómo estructurar recursos y endpoints en una API REST?

La base son los recursos: entidades que la aplicación maneja. En una API de productos, los recursos son productos, categorías y usuarios. Cada recurso debe tener un endpoint identificable y en plural para mantener consistencia.

¿Qué es un recurso y cómo se nombra en plural?

• Usa sustantivos en plural: products, categories, users.
• Cada recurso tiene un propósito único. Products gestiona productos. Categories gestiona categorías. Users gestiona usuarios.
• Identificadores únicos: cada elemento dentro de un recurso debe poder identificarse (por ejemplo, productId).

¿Cómo se forman las URLs por recurso?

• Patrón estándar: slash + nombre del recurso.

/products
/categories
/users

• Para un elemento específico, agrega el identificador como parámetro de ruta.

/products/{productId}

¿Cómo se relacionan productos y categorías?

• Un producto pertenece a una categoría y una categoría tiene muchos productos.
• Se documenta con atributos como categoryId en el body y con filtros por query params.

¿Qué operaciones http usar y qué respuestas esperar?

Sobre cada recurso, define las acciones con verbos HTTP: GET, POST, PUT, PATCH, DELETE. Documenta para cada una: URL, request, responses con status codes y ejemplos.

¿Cómo listar y obtener detalle con get?

• Lista de productos.

GET /products

• Responses esperadas.

  • 200: éxito.
  • 400: error en la petición.
  • 500: error del servidor.

• Detalle de un producto.

GET /products/{productId}

• Responses esperadas.
  • 200: éxito, encontrado.
  • 404: no encontrado.
  • 500: error del servidor.

¿Cómo crear un producto con post y qué headers usar?

• Creación de producto.

POST /products
Accept: application/json
Content-Type: application/json

• Body en JSON de la solicitud.

{
  "name": "T-shirt",
  "price": 40,
  "categoryId": 1
}

• Response esperado (el servidor asigna el id).

{
  "id": 1,
  "name": "T-shirt",
  "price": 40,
  "categoryId": 1
}

• Status codes.
  • 201: created.
  • 400: bad request.
  • 500: error del servidor.

¿Cómo actualizar con put o patch y cuándo eliminar con delete?

• Actualización completa.

PUT /products/{productId}
Accept: application/json
Content-Type: application/json

• Responses: 200 éxito, 400 bad request, 500 error del servidor.

• Actualización parcial.

PATCH /products/{productId}

• Mismo patrón de request/response que PUT, pero la edición es parcial.

• Eliminación.

DELETE /products/{productId}

• Responses.
  • 204: eliminación exitosa sin body.
  • 404: producto no encontrado.
  • 500: error del servidor.

¿Cómo definir bodies, headers y filtros con query params?

El body solo aplica cuando envías datos (por ejemplo, POST y PUT). Define el formato con headers y ejemplifica el contenido. Los filtros se documentan como query params en peticiones GET.

¿Qué headers y formatos usar con json?

• Indica siempre formato y aceptación de JSON.

Accept: application/json
Content-Type: application/json

• Justifica: asegura que lo enviado y lo recibido sea JSON.

¿Qué estructura de body necesitas para productos?

• Atributos clave en creación: name, price, categoryId.
• Diferencia clave: en creación no envías id; en la respuesta el servidor lo retorna.
• Relación entre recursos: categoryId vincula el producto con su categoría.

¿Cómo documentar filtros con query params?

• Filtro por categoría en la lista de productos.

GET /products?categoryId=1

• Explica el patrón: signo de interrogación + nombre del parámetro + valor.
• Aclara que aplica a peticiones GET para filtrar resultados.

—

Habilidades y conceptos que aplicarás de inmediato:

• Definir recursos y endpoints en plural con identificadores únicos.
• Mapear verbos HTTP a acciones del CRUD.
• Especificar headers y body en application/json.
• Documentar status codes claros: 200, 201, 204, 400, 404, 500.
• Diferenciar parámetros de ruta y query params en filtros.
• Describir relaciones entre recursos como product–category.

Te leo: completa la documentación de los endpoints para categorías y usuarios, compártela y comenta qué retos encontraste.