github.com/lucasvmiguel/stock-api

Stock API

Description

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.

Installing the app

Requirements:

• Go (>= 1.20)
• Docker
• Docker Compose

To install the go modules required to run the application, run the following command:

git clone [e-mail]:lucasvmiguel/stock-api.git
cd stock-api
make install

Running the app

1. Open a terminal and run the following command to start the persistence (database) required:

make persistence-up

1. In another terminal, start the application with the following command:

make run

Testing

Unit test

make test-unit

Integration test

1. Open a terminal and run the following command to start the persistence (database) required:

make persistence-up

1. In another terminal, run the integration test with the following command:

make test-integration

Stress test

Requirements:

• Apache AB

1. Open a terminal and run the following command to start the persistence (database) required:

make persistence-up

1. In a new terminal, start the application with the following command:

make run

1. In another terminal, run the stress test with the following command

make test-stress

Configuration

• 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

Architecture

This section describes what are the goals of the system and some of its design and implementation.

Requirements

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/or code) 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.

Schema

The following picture shows all the entities of the system.

System Design

The following pictures shows some of the details of how the system is designed and implemented.

Folder/File structure

• /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

Stack

• Language: Go
• API/REST framework: chi
• Database ORM: GORM
• Config reader: godotenv
• Database: Postgres
• Message Queue: Asynq

API Docs

In this section is described the REST API's endpoints (URL, request, response, etc).

Create product

Endpoint that creates a product

Request

Endpoint: [POST] /api/v1/products

Headers:
  Content-Type: application/json

Body:
  {
    "name": "Product name",
    "stock_quantity": 10
  }

Response

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

Request

Query Parameters

• cursor: use the response's next_cursor field
• limit: limit of products to be returned (min=1, max=100)

Endpoint: [GET] /api/v1/products?limit=10&cursor=2

Headers:
  Content-Type: application/json

Response

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)

Request

Endpoint: [GET] /api/v1/products/all

Headers:
  Content-Type: application/json

Response

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

Request

Endpoint: [GET] /api/v1/products/{id}

Headers:
  Content-Type: application/json

Response

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

Request

Endpoint: [PUT] /api/v1/products/{id}

Headers:
  Content-Type: application/json

Body:
  {
    "name": "new product name",
    "stock_quantity": 5
  }

Response

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

Request

Endpoint: [DELETE] /api/v1/products/{id}

Headers:
  Content-Type: application/json

Response

Success

Status: 204

Not Found

Status: 404

Internal Server Error

Status: 500

Configuration

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.

CI/CD

The project uses Github CI to run tests, builds (and possibly deployments). You can see the badge below:

Steps:

1. Set up Go
2. Build
3. Unit Test
4. Integration Test
5. Log in to the Container registry (Github)
6. Build and push Docker images

Important notes

• command make docker-run in development will only work correctly if the container's network is configured right. (More info here)

Roadmap

• Improvement: If it's needed to add more entities (eg: Product), we might need to centralize all entities in just one package. (Something like a entity 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