Cómo crear un objeto compuesto en una API REST
Estoy creando una API REST para mi aplicación y tengo una duda sobre cómo diseñar mi API siguiendo los principios de REST. Estoy usando PHP y Lumen, pero supongo que es más una duda de diseño que técnica.
Consideremos que tengo dos entidades:
Compañía:
- id
- nombre
Usuario:
- id
- nombre
- correo electrónico
- id_compañía
Cada Compañía debe tener uno o más Usuario, y me gustaría asegurar esa regla en mi API. Según mi entendimiento de las especificaciones de REST, debería crear un punto final para cada entidad, por lo que el cliente de la API debería hacer una solicitud POST a http:\\myserver\api\company para incluir una compañía, y luego hacer otra solicitud POST a http:\\myserver\api\company\{id}\users para incluir un Usuario en la nueva Compañía. El problema con ese enfoque es que el cliente solo podría crear una Compañía y dejarla sin Usuario.
En una API no REST, podría crear un método llamado createNewUser, que recibiría los datos del usuario junto con los datos de la Compañía, y este método se aseguraría de crear ambas entidades.
¿Cómo puedo lograr eso en una API REST?
davy.ai
En primer lugar, es importante destacar que el diseño de una API RESTful se centra más en el diseño orientado a recursos que en el diseño orientado a entidades. En este caso, los recursos serían las
empresasy losusuarios, y la API debería exponer las operaciones que se pueden realizar con estos recursos.Para crear una nueva empresa con uno o más usuarios, el punto de conexión `POST http://miservidor/api/empresas` debería aceptar un cuerpo de solicitud que contenga tanto los datos de la empresa como los datos del usuario. La API debería entonces crear la empresa y el/los usuario(s) en una única transacción, asegurando que ambas entidades se creen o ninguna se cree (utilizando transacciones de base de datos u otro mecanismo similar).
La respuesta del punto de conexión debería contener la empresa recién creada y su(s) usuario(s) asociado(s), junto con sus identificadores, para que el cliente pueda hacer referencia a ellos en las solicitudes siguientes.
Para actualizar una empresa con nuevos usuario(s), el punto de conexión `POST http://miservidor/api/empresas/{id}` podría aceptar un cuerpo de solicitud que contenga únicamente los datos del usuario. La API debería entonces crear el/los usuario(s) y asociarlos con la empresa existente, nuevamente utilizando una transacción para garantizar la atomicidad.
Al exponer estas operaciones en la API, el cliente puede crear y actualizar tanto empresas como usuarios, asegurando siempre el cumplimiento de la regla de que “cada empresa debe tener uno o más usuarios”.