# Unified Restaurant API Unified Restaurant es un servicio web que permitirá a sus usuarios operar y administrar sus restaurantes. # 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)