docs(crud-master): add first draft for API1 part

subjects/devops/crud-master/README.md

@@ -16,7 +16,60 @@ The API gateway will communicate in HTTP with `inventory` and using RabbitMQ for
 
 #### API 1: Inventory
 
+##### Definition of the API
+
+This API will be a CRUD (Create, Read, Update, Delete) RESTful API.
+It will interact with a PostgreSQL database.
+It will provide information about the products presents in the inventory of the store and allow users to do basic operations on it.
+
+A common way to do so is to use Express (TODO add a link?) which is a popular Node.js web framework.
+We will couple it with Sequelize (TODO add a link?), an ORM (TODO add a link?) which will abstract and simplify the interactions between our API and the database.
+
+Here are the entrypoints with the possible HTTP requests:
+
+- `/products`: GET, POST, DELETE
+- `/products/:id`: GET, PUT, DELETE
+- `/products/available`: GET
+
+Some details about each one of them:
+
+- `GET /products` retrieve all the products.
+- `GET /products?title=[name]` retrieve all the products with `name` in the title.
+- `POST /products` create a new product entry.
+- `DELETE /products` delete all products in the database.
+
+- `GET /products/:id` retrieve a single product by `id`.
+- `PUT /products/:id` update a single product by `id`.
+- `DELETE /products/:id` delete a single product by `id`.
+
+- `GET /products/available` retrieve all available the products.
+
+The API should work on `http://localhost:8080/`.
+
+(TODO add a link on how to setup it?)
+
+##### Defining the Database
+
+The database will be a PostgreSQL and it will be called `products`.
+Each product will have the following columns:
+
+- `id`: autogenerated unique identifier.
+- `title`: the title of the product.
+- `description`: the description of the product.
+- `available`: a boolean, it will be `true` if the product is available and `false` otherwise.
+
+(TODO add link on how to setup it?)
+
+##### Testing the API
+
+In order to test the correctness of your API you should use Postman (TODO add a link?). You could create one or more tests for every entrypoint and then export the configuration so you will be able to reproduce the tests on different machines easily.
+
+##### Documenting the API
+
+Good documentation is a very critical feature of every API. By design the APIs are meant for others to use, so there have been very good efforts to create standard and easy to implement ways to document it.
+
+As an introduction to the art of documenting you must SwaggerHub (TODO add a link?) with at least a meaningful description for each entrypoint. Feel free to implement any further and more complex feature.
+
 #### API 2: Billing
 
 #### The API Gateway
-