A Stock API is a REST API written in Go where products can be created, read, updated and deleted.
Note: This API has been configured for development
environment. To use in a production
environment, further setup will be required.
Requirements:
- Go (>= 1.20)
- Docker
- Docker Compose
To install the go modules required to run the application, run the following command:
git clone git@github.com:lucasvmiguel/stock-api.git
cd stock-api
make install
- Open a terminal and run the following command to start the persistence (database) required:
make persistence-up
- In another terminal, start the application with the following command:
make run
make test-unit
- Open a terminal and run the following command to start the persistence (database) required:
make persistence-up
- In another terminal, run the integration test with the following command:
make test-integration
Requirements:
- Open a terminal and run the following command to start the persistence (database) required:
make persistence-up
- In a new terminal, start the application with the following command:
make run
- In another terminal, run the stress test with the following command
make test-stress
- To configure how the app will run, check the following file: .env
- To configure how the app will be built and released, check the following file: Makefile
This section describes what are the goals of the system and some of its design and implementation.
The following list shows all user requirements implemented by the system.
- As a user, I can fetch all products using a REST API.
- As a user, I can fetch a paginated list of products using a REST API.
- As a user, I can fetch a product by its id using a REST API.
- As a user, I can create a product using a REST API.
- As a user, I can update some fields (
name
and/orcode
) of a product by its id using a REST API. - As a user, I can delete a product by its id using a REST API.
The following picture shows all the entities of the system.
The following pictures shows some of the details of how the system is designed and implemented.
/cmd
: Main applications for this project./cmd/api
: Package responsible for starting the API application./cmd/api/starter
: Package containing all code required for starting the API application. (eg: config, routes, etc)/internal
: Private application and library code./internal/product
: Product domain, where every code related to product should be placed. (Inspired by DDD)/pkg
: Library code that's ok to use by external applications (eg:/pkg/mypubliclib
)./test
: Integration tests that run with external apps. (eg: database)/.github
: CI/CD from Github.docker-compose.yml
: Used to spin up the persistence layer in development and testing..env
: configures project.Makefile
: Project's executable tasks.
Note: inspired by https://github.com/golang-standards/project-layout
- Language: Go
- API/REST framework: chi
- Database ORM: GORM
- Config reader: godotenv
- Database: Postgres
- Message Queue: Asynq
In this section is described the REST API's endpoints (URL, request, response, etc).
Create product
Endpoint that creates a product
Endpoint: [POST] /api/v1/products
Headers:
Content-Type: application/json
Body:
{
"name": "Product name",
"stock_quantity": 10
}
Success
Status: 201
Body:
{
"id": 1,
"name": "Product name",
"code": "70a17d32-a670-4396-9706-bd0940152fc7",
"stock_quantity": 10,
"created_at": "2022-07-08T18:53:57.936433+01:00",
"updated_at": "2022-07-08T18:53:57.936433+01:00"
}
Bad Request
Status: 400
Internal Server Error
Status: 500
Get products paginated
Endpoint to get products paginated
cursor
: use the response'snext_cursor
fieldlimit
: limit of products to be returned (min=1, max=100)
Endpoint: [GET] /api/v1/products?limit=10&cursor=2
Headers:
Content-Type: application/json
Success
Status: 200
Body:
{
"items": [
{
"id": 1,
"name": "foo",
"code": "70a17d32-a670-4396-9706-bd0940152fc7",
"stock_quantity": 1,
"created_at": "2022-07-08T18:53:57.936433+01:00",
"updated_at": "2022-07-08T18:53:57.936433+01:00"
}
],
"next_cursor": 2
}
Bad Request
Status: 400
Internal Server Error
Status: 500
Get all products
Endpoint to get all products (does not have pagination)
Endpoint: [GET] /api/v1/products/all
Headers:
Content-Type: application/json
Success
Status: 200
Body:
[
{
"id": 1,
"name": "foo",
"code": "70a17d32-a670-4396-9706-bd0940152fc7",
"stock_quantity": 1,
"created_at": "2022-07-08T18:53:57.936433+01:00",
"updated_at": "2022-07-08T18:53:57.936433+01:00"
}
]
Internal Server Error
Status: 500
Get product by id
Endpoint to get a product by id
Endpoint: [GET] /api/v1/products/{id}
Headers:
Content-Type: application/json
Success
Status: 200
Body:
{
"id": 1,
"name": "foo",
"code": "70a17d32-a670-4396-9706-bd0940152fc7",
"stock_quantity": 1,
"created_at": "2022-07-08T18:53:57.936433+01:00",
"updated_at": "2022-07-08T18:53:57.936433+01:00"
}
Not Found
Status: 404
Internal Server Error
Status: 500
Update product by id
Endpoint that updates a product by id
Endpoint: [PUT] /api/v1/products/{id}
Headers:
Content-Type: application/json
Body:
{
"name": "new product name",
"stock_quantity": 5
}
Success
Status: 200
Body:
{
"id": 1,
"name": "new product name",
"code": "70a17d32-a670-4396-9706-bd0940152fc7",
"stock_quantity": 5,
"created_at": "2022-07-08T18:53:57.936433+01:00",
"updated_at": "2022-07-08T18:53:57.936433+01:00"
}
Bad Request
Status: 400
Not Found
Status: 404
Internal Server Error
Status: 500
Delete product by id
Endpoint to delete a product by id
Endpoint: [DELETE] /api/v1/products/{id}
Headers:
Content-Type: application/json
Success
Status: 204
Not Found
Status: 404
Internal Server Error
Status: 500
A file called .env
has all config used in the project.
In the future, a service like Doppler or Vault could (and should) be used in the project.
The project uses Github CI to run tests, builds (and possibly deployments). You can see the badge below:
Steps:
- Set up Go
- Build
- Unit Test
- Integration Test
- Log in to the Container registry (Github)
- Build and push Docker images
- command
make docker-run
indevelopment
will only work correctly if the container's network is configured right. (More info here)
Improvement
: Add Google's wire DI library to the project.Improvement
: If it's needed to add more entities (eg: Product), we might need to centralize all entities in just one package. (Something like aentity
package) That way, we would prevent cycle dependencies. (Check this link)Improvement
: API docs are being described on the Readme. However, OpenAPI might be a good improvement in the future.Improvement
: Using a secret management service like Doppler or Vault