Guía de Diseño de API: Construyendo APIs que tus Usuarios Amarán

Una API mal diseñada es un impuesto sobre cada desarrollador que la usa. Una API bien diseñada se siente natural y escala sin romperse.

Principios de API REST

1. Usa Sustantivos, No Verbos

Malo:

```

GET /api/getUsers

POST /api/createUser

DELETE /api/deleteUserById?id=123

```

Bueno:

```

GET /api/users

POST /api/users

DELETE /api/users/123

```

2. Los Códigos de Estado HTTP Importan

No uses 200 para todo:

```

200 OK → La solicitud fue exitosa

201 Created → Se creó el recurso

204 No Content → Éxito, sin cuerpo de respuesta

400 Bad Request → Error del cliente

401 Unauthorized → Se requiere autenticación

403 Forbidden → Autenticado pero no permitido

404 Not Found → El recurso no existe

500 Server Error → Algo se rompió de nuestro lado

```

3. Formato de Respuesta Consistente

Cada respuesta debe seguir la misma estructura:

```json

{

"success": true,

"data": { "id": 123, "name": "Juan" }

}

```

4. Paginación para Listas

Nunca devuelvas millones de registros de una vez:

```

GET /api/users?page=1&limit=50

```

5. Filtrado y Ordenamiento

Permite a los clientes especificar los datos que quieren:

```

GET /api/users?status=active&sort=created_at:desc

```

Conclusión

Una API bien diseñada escala y se siente natural. Construimos excelentes APIs en mznah.