skrd/unified-restaurant-original

Fork 0

Files

Daniel Cortés 6a957b02ab Corrregido error en response de la API en documentacion

2021-04-30 22:23:46 -04:00

7.5 KiB

Raw Blame History

Unified Restaurant API

Unified Restaurant es un servicio web que permitirá a sus usuarios operar y administrar sus restaurantes.

[[TOC]]

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

{
    "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

{
    "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

{
    "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

{
    "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

{
    "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.

{
    "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} donde {id} es el ID del usuario a buscar, este ID puede ser el UUID del usuario o el ID entregado por Auth0, 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

{
    "nombre": "Jhon 2"
}

O si se quieren cambiar sus roles, se envía el siguiente payload

{
    "roles": [
        "admin",
        "recaudador"
    ]
}

Una vez se modifiquen los datos del usuario, la API responderá con el usuario actualizado

{
    "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

Eliminar

Para eliminar a un usuario hay que enviar un DELETE a la ruta /api/v1/user/{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.

Los usuarios eliminados podrán ser recuperados localmente, pero en auth0 serán eliminados permanentemente y su asociación con restaurantes se perderá.

La respuesta de la API al eliminar será un código 204 sin cuerpo, pero ante cualquier error, principalmente proviniendo desde Auth0, se utilizará el cuerpo de error definido al inicio.

7.5 KiB Raw Blame History