Contenido del curso
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?
¿Cómo se forman las URLs por recurso?
/products /categories /users
/products/{productId}
¿Cómo se relacionan productos y categorías?
¿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?
GET /products
Responses esperadas.
Detalle de un producto.
GET /products/{productId}
¿Cómo crear un producto con post y qué headers usar?
POST /products Accept: application/json Content-Type: application/json
{ "name": "T-shirt", "price": 40, "categoryId": 1 }
{ "id": 1, "name": "T-shirt", "price": 40, "categoryId": 1 }
¿Cómo actualizar con put o patch y cuándo eliminar con delete?
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}
¿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?
Accept: application/json Content-Type: application/json
¿Qué estructura de body necesitas para productos?
¿Cómo documentar filtros con query params?
GET /products?categoryId=1
—
Habilidades y conceptos que aplicarás de inmediato:
Te leo: completa la documentación de los endpoints para categorías y usuarios, compártela y comenta qué retos encontraste.
Samuel Steven Bernal Martínez
Luis Tapia
JUAN DAVID CORRALES AGUILAR
Jesus Heriberto Lara Juarez
Carlos Naveda
Angelica Garcia
Angelica Garcia
Kevin Sierra
José María Caamaño González
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!
100%. buenas prácticas desde el principio :)
Aprendí como documentar. Aún no había visto esto en algún curso... y adicional aprendí a hacer ( `este símbolo` en mi teclado probando
siempre puedes ver una tabla de codigo ascci para saber que simbolo saldra alt+64 = @
Tarea realizada
Hola, comparto la documentación realizada ✨
# RECURSOS ## Productos URL: `/products` ### Lista de Productos `GET /products` #### Filtros - Categorias: `GET /products/?categoryId={category_id}` #### Response - 200: Exito - 400: Error en la petición - 500: Error de Servidor ### Detalle de Producto `GET /products/{productId}` #### Response - 200: Exito - 404: No fue encontrado - 500: Error en el servidor ### Crear Producto `POST /products` #### Request - Headers: - `Content-Type = application/json` - `Accept = application/json` - Body: ```json { "name": "T-Shirt", "price": 40, "categoryId": 1 } ``` #### Response - 201: Created - 400: Bad Request - 500: Error en el servidor ```json { "id": 1, "name": "T-Shirt", "price": 40, "categoryId": 1 } ``` ### Edición `PUT /products/{productId}` #### Request - Headers: - `Content-Type = application/json` - `Accept = application/json` - Body: ```json { "name": "T-Shirt Black", "price": 30, "categoryId": 2 } ``` #### Response - 200: Exito en la petición - 400: Bad Request - 500: Error en el servidor ```json { "id": 1, "name": "T-Shirt Black", "price": 30, "categoryId": 2 } ``` ### Edición Parcial `PATCH /products/{productId}` #### Request - Headers: - `Content-Type = application/json` - `Accept = application/json` - Body: ```json { "price": 35 } ``` #### Response - 200: Exito en la petición - 400: Bad Request - 500: Error en el servidor ```json { "id": 1, "name": "T-Shirt", "price": 35, "categoryId": 1 } ``` ### Eliminación `DELETE /products/{productId}` #### Response - 204: Empty Response - 404: Not Found - 500: Error en el servidor --- ## Categorias URL: `/categories` ### Lista de Categorias `GET /categories` #### Response - 200: Exito - 400: Error en la petición - 500: Error de Servidor ### Detalle de la Categoria `GET /categories/{categoryId}` #### Response - 200: Exito - 404: No fue encontrado - 500: Error en el servidor ### Crear Categoria `POST /categories` #### Request - Headers: - `Content-Type = application/json` - `Accept = application/json` - Body: ```json { "name": "Ropa", "description": "Productos textiles y accesorios", "isActive": true } ``` #### Response - 201: Created - 400: Bad Request - 500: Error en el servidor ```json { "id": 1, "name": "Ropa", "description": "Productos textiles y accesorios", "isActive": true } ``` ### Edición `PUT /categories/{categoryId}` #### Request - Headers: - `Content-Type = application/json` - `Accept = application/json` - Body: ```json { "name": "Moda", "description": "Productos textiles y accesorios", "isActive": true } ``` #### Response - 200: Exito en la petición - 400: Bad Request - 500: Error en el servidor ```json { "id": 1, "name": "Moda", "description": "Productos textiles y accesorios", "isActive": true } ``` ### Edición Parcial `PATCH /categories/{categoryId}` #### Request - Headers: - `Content-Type = application/json` - `Accept = application/json` - Body: ```json { "name": "Moda" } ``` #### Response - 200: Exito en la petición - 400: Bad Request - 500: Error en el servidor ```json { "id": 1, "name": "Moda", "description": "Productos textiles y accesorios", "isActive": true } ``` ### Eliminación `DELETE /categories/{categoryId}` #### Response - 204: Empty Response - 404: Not Found - 500: Error en el servidor --- ## Users URL: `/users` ### Lista de Usuarios `GET /users` #### Response - 200: Exito - 400: Error en la petición - 500: Error de Servidor ### Detalle de Usuario `GET /users/{userId}` #### Response - 200: Exito - 404: No fue encontrado - 500: Error en el servidor ### Crear Usuario `POST /users` #### Request - Headers: - `Content-Type = application/json` - `Accept = application/json` - Body: ```json { "name": "John Doe", "email": "john@example.com", "password": "secret123" } ``` #### Response - 201: Created - 400: Bad Request - 500: Error en el servidor ```json { "id": 1, "name": "John Doe", "email": "john@example.com" } ``` ### Edición `PUT /users/{userId}` #### Request - Headers: - `Content-Type = application/json` - `Accept = application/json` - Body: ```json { "name": "John Smith", "email": "johnsmith@example.com", "password": "newpassword123" } ``` #### Response - 200: Exito en la petición - 400: Bad Request - 500: Error en el servidor ```json { "id": 1, "name": "John Smith", "email": "johnsmith@example.com" } ``` ### Edición Parcial `PATCH /users/{userId}` #### Request - Headers: - `Content-Type = application/json` - `Accept = application/json` - Body: ```json { "email": "johnsmith@example.com" } ``` #### Response - 200: Exito en la petición - 400: Bad Request - 500: Error en el servidor ```json { "id": 1, "name": "John Doe", "email": "johnsmith@example.com" } ``` ### Eliminación `DELETE /users/{userId}` #### Response - 204: Empty Response - 404: Not Found - 500: Error en el servidor
Me encanto esta clase 🤩
Me quedaría la duda al usar PATCH, si es necesario pasar un Body en la Request?
Busqué un poco y encuentro que no es necesario, pero que a su vez puede ser viable...
\## Categories URL: `/categories` \### Lista de categorias `GET /categories` \#### Response \- 200: éxito \- 400: error en la petición \- 500: error en el servidor \### Crear categoría `POST /categories` \#### Request \- headers:   `Content-Type: application/json`   `Accept: application/json` \- body: ``` json {   "name": "shirts", }
#### Response
- 201: Created
- 400: Bad Request
- 500: Error en el servidor
{   "categoryId": 1,   "name": "shirts", }
### Renombrar una categoría
PATCH /categories/{category\_id}/
#### Request
- Headers:
- Content-Type = application/json
- Accept = application/json
#### Response
- 200: Éxito
- 400: Bad Request
- 500: Error en el servidor
### Eliminar una categoría
DELETE /categories/?categoryId={category\_id}
#### Response
- 204: Empty Response
- 404: Not found
- 500: Error en el servidor
Sí. En los métodos PATCH, POST y PUT; siempre es necesario un Body, con los datos que se van a crear o modificar. Además, en los métodos PATCH y PUT, también es necesario el product_id, para identificar el producto que quieres modificar.
