| Petición | Quién puede llamar | Éxito |
|---------|--------------|---------|
| GET /api/licenses | licenses:read | 200, una lista. ?search= la filtra |
| POST /api/licenses | licenses:write | 201, una licencia |
| DELETE /api/licenses/{license} | licenses:write | 202, encolado |
| POST /api/license-batches | licenses:write | 202, un ID de lote |
| GET /api/license-batches/{id} | licenses:write, su dueño | 200, el progreso |
| POST /api/exports | licenses:read | 202, un ID de exportación |
| GET /api/exports/{id} | licenses:read, su dueño | 302, un enlace que caduca |
| GET /api/consumers | operadores | 200, paginado |
| POST /api/consumers | operadores | 201, un consumidor |
| GET /api/consumers/{consumer} | operadores, o él mismo | 200 |
| PATCH /api/consumers/{consumer} | operadores | 200. Fija los límites y el webhook |
| DELETE /api/consumers/{consumer} | operadores | 204 |
| GET /api/consumers/{consumer}/tokens | operadores | 200, sin secretos |
| POST /api/consumers/{consumer}/tokens | operadores | 201, el token, una vez |
| DELETE .../tokens/{token} | operadores | 204 |
| GET /up | cualquiera | 200 cuando la instancia puede atender |
Un operador es quien llama con un token que tiene la habilidad consumers:manage.
Cabeceras de la petición
| Cabecera | Propósito | Capítulo |
|--------|---------|---------|
| Authorization: Bearer ... | Identifica al consumidor | 4 |
| Accept-Language | Idioma de los mensajes | 6 |
| X-Trace-Id | Un UUID que recorre los logs y los jobs | 7 |
| Idempotency-Key | Un UUID que hace seguro reintentar un POST | 8 |
| Api-Version | Forma de la respuesta | 16 |
Respuestas cuando algo va mal
| Estado | code | Significado |
|--------|--------|---------|
| 400 | | La Idempotency-Key no es un UUID |
| 401 | | No hay un token válido |
| 403 | | El token no puede hacer esto |
| 404 | | No se encontró, o no te corresponde verlo |
| 409 | request_in_progress | La misma petición sigue en curso |
| 409 | license_limit_reached | El consumidor está en su límite |
| 422 | | Falló la validación. Mira errors, por campo. Sin errors, se reutilizó una clave de idempotencia |
| 429 | | Se alcanzó el límite de peticiones. Mira Retry-After |
| 502 | provider_failed | El proveedor tuvo un error. Reintenta |
| 502 | provider_rejected | El proveedor rechazó la petición. No reintentes |
| 504 | provider_unavailable | El proveedor no contestó. Reintenta |
| 500 | | Un fallo de esta API |
Todas tienen un message.
Dónde vive cada cosa
| Asunto | Archivo |
|---------|------|
| Rutas | routes/api.php |
| Middleware, excepciones | bootstrap/app.php |
| HTTP de entrada y de salida | app/Http/Controllers |
| El pipeline de la petición | app/Http/Middleware |
| Validación | app/Http/Requests |
| Forma de la salida | app/Http/Resources |
| Integración con el proveedor y datos tipados | app/Services/License |
| El nombre con el que la aplicación la llama | app/Facades |
| Habilidades, códigos de error, versiones | app/Enums |
| Reglas de validación propias | app/Rules |
| Autorización sobre registros | app/Policies |
| Datos que son tuyos | app/Models |
| Fallos con nombre | app/Exceptions |
| Trabajo en segundo plano | app/Jobs, app/Listeners |
| Trabajo que se inicia desde una terminal | app/Console/Commands |
| Limitador de peticiones, comprobaciones de salud | app/Providers/AppServiceProvider.php |
| Programaciones | routes/console.php |
| Ventanas de retención, fechas de versiones | config/retention.php, config/api.php |