The main goal of this task is to consolidate the concepts related to the specification of a service. For this purpose, the definition of a service will be defined and published using the OpenAPI 3 standard. Additionally, the behaviour of the service will be simulated (the use of Stoplight Prism, Postman, ... is proposed).
To achieve this goal, a set of services will be defined and then used to develop a product warehouse management application. First, teams of a maximum of three students will be formed, and each team will have to specify one of the proposed services.
In order to publish the specification, a docker container must be generated to provide the definition of the operations available in the service and describe the connections with other services. The services and the different functionalities that must be implemented must perform the following complete functionalities:
- Product Management
- Adding, deleting and modifying products
- Adding, deleting and changing categories
- Product search with free text
- Listing of products in a category
- All operations are events to be recorded
- Order Management
- Adding, deleting and modifying orders
- Order search by type, status, product, organization (customer or supplier) and free text
- Checking the stock of a product (bought and received - sold and sent or received)
- All operations are events to be recorded
- Event Logging [MICROSERVICE DEVELOPED]
- Event registration
- Evenet search by origin, level, date range and free text
- CSV dumping of all events from a given source
- All operations are events to be recorded
- Billing
- Adding, deleting and modifying organizations
- Registration and cancellation of invoices
- Changing an invoice means cancelling it and creating a new one with the changes
- Invoice search by organization (customer), date range, status and free text
- All operations are events to be recorded
- The design of each service will take into account that each service must have its own persistence mechanism
- A single compressed file must be sent in which all the files necessary to deploy the assigned service are attached. A
README.md
file must be included, containing the necessary instructions to deploy the developed project - To carry out this practice, groups of 3 students will be formed. Those students who opt for evaluation by final test only will do the task individually. The service assigned to each student or group of students will be published on the platform.
The microservice developed has been logging, which is specificated in this file.
The scheme to follow according to the practice statement is the following:
Evento:
title: Evento
type: objet
properties:
evento:
type: object
properties:
idEvento:
type: integer
format: int64
example: 878923748
minimum: 1
origen:
type: string
example: "PEDIDOS"
fecha:
type: string
format: "date-time"
mensaje:
type: string
nivel:
type: string
enum:
- "info"
- "warn"
- "error"
_links:
type: object
description: link relations
properties:
parent:
type: object
properties: {"href": { "type": "string", "format": "url" }}
self:
type: object
properties: {"href": { "type": "string", "format": "url" }}
x-examples:
ejemplo-1:
idEvento: 89776253
origen: "PEDIDOS"
fecha: "2020-03-08T18:30:55.855Z"
mensaje: "Pedido (compra) 127 realizado. Producto: 12. Cantidad: 2. Organización: 32165478"
nivel: "info"
_links:
parent:
href: /eventos
self:
href: /eventos/89776253
The microservice has the following endpoints:
- /events
- OPTIONS
- GET (application/json | text/csv) [?query=search]
- POST (application/json)
- /events/{eventId}
- OPTIONS
- GET (application/json | text/csv)
In addition, the ETag
header is used for GET
responses, the Allow
header is used for OPTIONS
responses and the Location
header is used for POST
responses.
It also has a security mechanism through an X-API-Key
in the header, in order to guarantee the security of access and manipulation of the API data.
Finally, like all HTTP
services, a response code is returned for each request made in order to know if the request was successful or, if not, an error message informing about what happened.
For the interaction with the microservice specification, Swagger UI
will be used, a user interface that allows the display and manipulation of OpenAPI services. In addition, Prism
will be used, a mock server that will allow us to recreate the operation of the service without the need to implement it.
It should be noted that the latter has errors in its different versions, so I have made a fork
of version 3.2.9 applying one of the patches of version 3.3.1 to handle the OPTIONS
requests with the CORS
header.
- Docker Engine
18.06.0
or higher (make sure the service is running).
Open a terminal (with administrator privileges if the Docker pipeline does not have such permissions assigned) and go to the root directory of this project. Then run the following command to up the microservices:
foo@bar:~$ docker-compose -f docker-compose.yaml up
If this fails, make sure you don't have any Docker containers with the same name running, and don't use the same port (if necessary, change the port in the docker-compose.yaml
file).
Open the browser and type localhost
(if you have changed the port, type the port as follows: localhost:<port>
).
Once there, you can test, as indicated by the Swagger UI user interface, each of the available requests along with the required parameters. You can also view the console-generated logs to see how the requests are made and how the mock server resolves them.
Once the manipulation of the microservice has been completed, you can end the execution of the microservice with Ctrl + C
.
You should also remove the created containers to avoid future problems, as the Prism server requires their removal if you want to re-launch the container (otherwise it will not work). To do this you must execute the following command:
foo@bar:~$ docker-compose -f docker-compose.yaml rm
These steps should also be performed if by any chance the service fails while running and needs to be restarted, stopping and removing the containers created first and launching them again for proper execution.