Que buena forma de abordar la enseñanza, anotando primero lo que necesitamos y cómo se usará después, iniciar por la parte de la documentación y decir en voz alta el proceso de pensamiento para llegar ahi es algo que pocos cursos hacen, ojalá ver más este formato, se aprende mucho asi!
Recursos
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.
