Documentación de API REST con editor de texto

Clase 8 de 17 • Curso de API REST con Javascript

Clase anteriorSiguiente clase

Resumen

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.