Documentacion de la api en el readme
This commit is contained in:
@@ -3,12 +3,242 @@
|
||||
Unified Restaurant es un servicio web que permitirá a sus usuarios operar y
|
||||
administrar sus restaurantes.
|
||||
|
||||
## Documentación
|
||||
# Documentación
|
||||
|
||||
Esta API tendrá los siguientes endpoints
|
||||
|
||||
| Funcionalidad | Endpoint |
|
||||
| --------------- | ----------------- |
|
||||
| Usuario | `/api/v1/users/` |
|
||||
| Bodega | `/api/v1/bodega/` |
|
||||
| Venta | `/api/v1/venta/` |
|
||||
| Administración | `/api/v1/admin/` |
|
||||
|
||||
## Errores
|
||||
|
||||
En caso que se presente algún error la API siempre responderá con un mensaje de
|
||||
la siguiente forma
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "error_code",
|
||||
"message": "Mensaje explicativo del error en español"
|
||||
}
|
||||
```
|
||||
|
||||
Ahora, si el error lo presento Auth0, el campo de `error` siempre empezara el
|
||||
código con `auth0_`, es util saber que el error es enviado desde Auth0 porque
|
||||
sus mensajes de error están en ingles y si se deben mostrar al usuario se
|
||||
deberán traducir manualmente
|
||||
|
||||
## Usuario
|
||||
|
||||
La API de usuario permite manipular a los usuarios de la aplicación, las
|
||||
siguientes acciones están disponibles
|
||||
|
||||
### Obtener todos
|
||||
|
||||
Para obtener la lista completa de usuarios se debe enviar un `GET` a la
|
||||
ruta `/api/v1/user`, estos datos serán paginados, por lo que opcionalmente se
|
||||
recibe el parámetro `page` para definir la página a obtener y el
|
||||
parámetro `per_page` para definir cuantos elementos obtener por página.
|
||||
|
||||
La respuesta de la API tiene la siguiente forma
|
||||
|
||||
```json
|
||||
{
|
||||
"pagination": {
|
||||
"per_page": 15,
|
||||
"from": 1,
|
||||
"to": 2,
|
||||
"total": 2,
|
||||
"current_page": 1,
|
||||
"last_page": 1,
|
||||
"links": {
|
||||
"first": "http://localhost:8080/api/v1/users?page=1&per_page=15",
|
||||
"prev": null,
|
||||
"current": "http://localhost:8080/api/v1/users?page=1&per_page=15",
|
||||
"next": null,
|
||||
"last": "http://localhost:8080/api/v1/users?page=1&per_page=15"
|
||||
}
|
||||
},
|
||||
"data": [
|
||||
// listado de usuarios
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
La respuesta contendrá una serie de datos indicando el estado de la paginación,
|
||||
además de una serie de links indicando a donde llamar para obtener la primera,
|
||||
anterior, actual, siguiente y última página.
|
||||
|
||||
Estos links pueden ser null en caso que no sea posible utilizarlo, por ejemplo
|
||||
si hay 3 páginas y la página actual es la 3, el link `next` será nulo, ya que no
|
||||
hay una cuarta página.
|
||||
|
||||
### Obtener Usuario
|
||||
|
||||
Para obtener un usuario se debe hacer un `GET` a la ruta `/api/v1/users/{id}`
|
||||
donde `{id}` es el ID del usuario a buscar, este ID puede ser el UUID del
|
||||
usuario o el ID entregado por auth0, esto puede ser util si el frontend tiene
|
||||
solamente acceso al ID entregado por auth0.
|
||||
|
||||
Si el ID de usuario existe, la siguiente sera la respuesta de la API
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "4014fd8d-26fd-4ce8-bdaa-99b8a325ee92",
|
||||
"auth0_id": "123456",
|
||||
"nombre": "Mesero",
|
||||
"created_at": "2021-04-26T16:37:59.998642Z",
|
||||
"updated_at": "2021-04-26T16:37:59.998642Z",
|
||||
"deleted_at": null,
|
||||
"roles": [
|
||||
"mesero"
|
||||
],
|
||||
"restaurantes": [
|
||||
{
|
||||
"id": "63f62e17-e011-4f6f-8c15-5eb65a5014be",
|
||||
"nombre": "Todo Rico Restaurant",
|
||||
"created_at": "2021-04-26T16:37:59.181869Z",
|
||||
"updated_at": "2021-04-26T16:37:59.181869Z",
|
||||
"deleted_at": null,
|
||||
"pivot": {
|
||||
"usuario_id": "4014fd8d-26fd-4ce8-bdaa-99b8a325ee92",
|
||||
"restaurante_id": "63f62e17-e011-4f6f-8c15-5eb65a5014be"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
En caso que el usuario no exista se retornara el siguiente mensaje de error
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "user_not_found",
|
||||
"message": "El usuario con id o auth0_id {id} no existe"
|
||||
}
|
||||
```
|
||||
|
||||
### Crear
|
||||
|
||||
Para crear un nuevo usuario se debe enviar un `POST` a la ruta `/api/v1/user`
|
||||
con un payload como el del siguiente ejemplo
|
||||
|
||||
```json
|
||||
{
|
||||
"nombre": "John Doe",
|
||||
"email": "john@doe.com",
|
||||
"username": "johndoe",
|
||||
"password": "superPasswordWith123NumbersAnd----Symbols",
|
||||
"roles": [
|
||||
"admin",
|
||||
"recaudador",
|
||||
"mesero",
|
||||
"productor"
|
||||
],
|
||||
"restaurant": "63f62e17-e011-4f6f-8c15-5eb65a5014be"
|
||||
}
|
||||
```
|
||||
|
||||
Esto creará el usuario John Doe localmente y en auth0 por lo cual él podrá
|
||||
entrar con el email y contraseña indicados
|
||||
|
||||
Una vez creado, la API responderá con el usuario creado, no contendrá `username`
|
||||
,
|
||||
`email` ni `password` ya que estos valores los utiliza Auth0 y no son relevantes
|
||||
para el modelo.
|
||||
|
||||
```json
|
||||
{
|
||||
"usuario": {
|
||||
"id": "6430c9ac-6bce-4e23-8421-28bce08101d4",
|
||||
"auth0_id": "auth0|608ba7866c9b520074d687d9",
|
||||
"nombre": "John Doe",
|
||||
"roles": [
|
||||
"admin",
|
||||
"recaudador",
|
||||
"mesero",
|
||||
"productor"
|
||||
],
|
||||
"updated_at": "2021-04-30T06:45:22.000000Z",
|
||||
"created_at": "2021-04-30T06:45:22.000000Z",
|
||||
"restaurantes": [
|
||||
{
|
||||
"id": "63f62e17-e011-4f6f-8c15-5eb65a5014be",
|
||||
"nombre": "Todo Rico Restaurant",
|
||||
"created_at": "2021-04-26T16:37:59.181869Z",
|
||||
"updated_at": "2021-04-26T16:37:59.181869Z",
|
||||
"deleted_at": null,
|
||||
"pivot": {
|
||||
"usuario_id": "4014fd8d-26fd-4ce8-bdaa-99b8a325ee92",
|
||||
"restaurante_id": "63f62e17-e011-4f6f-8c15-5eb65a5014be"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Actualizar
|
||||
|
||||
Para actualizar un usuario se debe enviar un `POST` a la
|
||||
ruta `/api/v1/users/{id}` y en el cuerpo se debe indicar los campos a
|
||||
actualizar.
|
||||
|
||||
Por ejemplo para actualizar el nombre del usuario se envía el siguiente payload
|
||||
|
||||
```json
|
||||
{
|
||||
"nombre": "Jhon 2"
|
||||
}
|
||||
```
|
||||
|
||||
O si se quieren cambiar sus roles, se envía el siguiente payload
|
||||
|
||||
```json
|
||||
{
|
||||
"roles": [
|
||||
"admin",
|
||||
"recaudador"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Una vez se modifiquen los datos del usuario, la API responderá con el usuario
|
||||
actualizado
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "340c8e54-9a15-4bd2-9b59-108f267d5872",
|
||||
"auth0_id": "auth0|608ca16fcfc3df0068fea6a4",
|
||||
"nombre": "Jhon 2",
|
||||
"created_at": "2021-04-30T18:31:44.000000Z",
|
||||
"updated_at": "2021-05-01T00:31:52.000000Z",
|
||||
"deleted_at": null,
|
||||
"roles": [
|
||||
"admin",
|
||||
"recaudador"
|
||||
],
|
||||
"restaurantes": [
|
||||
{
|
||||
"id": "63f62e17-e011-4f6f-8c15-5eb65a5014be",
|
||||
"nombre": "Todo Rico Restaurant",
|
||||
"created_at": "2021-04-26T16:37:59.181869Z",
|
||||
"updated_at": "2021-04-26T16:37:59.181869Z",
|
||||
"deleted_at": null,
|
||||
"pivot": {
|
||||
"usuario_id": "340c8e54-9a15-4bd2-9b59-108f267d5872",
|
||||
"restaurante_id": "63f62e17-e011-4f6f-8c15-5eb65a5014be"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Ahora existe la posibilidad que se quieran actualizar multiples casos a la vez,
|
||||
si esto es asi, hay que tomar en cuenta las limitaciones impuestas por Auth0,
|
||||
donde ciertos campos no se pueden cambiar al mismo tiempo, para más detalles,
|
||||
ver
|
||||
la [documentación de Auth0](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id)
|
||||
|
||||
Reference in New Issue
Block a user