API Seed

The seed from which your software grows.

Project setup

Clone the project locally

If you have SSH setup on your account, run the following command:

$ git clone [email protected]:alexcristea/api-seed.git

Otherwise, you may use the HTTPS version (might ask for username and password):

$ git clone https://github.com/alexcristea/api-seed.git

Install dependencies

Change the working directory to the repo directory:

cd api-seed

If you're developing on macOS, then run the setup-macos.sh script. It will install the system dependencies, project dependencies and the evironment for your app:

bash ./bin/setup-macos.sh

Otherwise, make sure to manually install Node.js and yarn on your machine before continuing with the development.

$ node --version
v11.14.0

$ yarn --version
1.22.4

To install the project dependencies, run the following install command:

$ yarn

Development

To configure the hostname and port (default: localhost:8080) of the web server, make sure to configure the environment variables in the .env file:

cp .example.env .env

or copy the next lines into your .env file:

HOSTNAME='localhost'
PORT=8080

Run in development mode

To start the project in development mode, run the following command from the root directoy of the project:

$ yarn dev

Run in watch mode

To continuously watch for file changes and check for syntax errors, run the following command:

$ yarn dev:watch

Run unit tests

To run the unit test, run the following command from the root directoy of the project:

$ yarn test

To continuously run the unit tests as you code, run the following command:

$ yarn test:watch

The generated tests reports are available in ./reports/test-results.html file.

Generate code coverage report

To generate the coverage report for your app, run the following command:

$ yarn test:coverage

The generated report is available in ./reports/coverage directory.

Build for production

To transpile the TypeScript files into JavaScript, run the following command from the root directoy of the project:

$ yarn build

Run for production

To build and start the transpiled project, run the following command from the root directoy of the project:

$ yarn start

Project checks

To run type, linting and prettier checks on your project, run the following command from the root directoy of the project:

$ yarn check:all

Alternatively, you can run the scripts independently:

$ yarn check:type
$ yarn check:lint
$ yarn check:prettier

Futhermore, to check for project dependency cycles, run the following command from the root directoy of the project:

$ yarn check:dpdm

Docker

Make sure to have Docker installed on your machine.

$ docker --version
Docker version 19.03.5, build 633a0ea

To build the Docker image, run the following command from the root directoy of the project:

$ yarn docker:build

To run the Docker image, run the following command from the root directoy of the project:

$ yarn docker:run

Documentation

For the project technical documentation we use the README.md file.

For the API documentation we use sagger with the openapi 3.0 format. It is available in the ./src/delivery/api/openapi.yml and its accessible at the /docs endpoint.

Architecute and design

The tests document the full behaviour of the project functionality.

At this stage, the delivery mechanism is a simple http server that takes the input, sends it to the sayHello() function and returns the output to the caller. If an exception appears along the way, it will respond with a 400 error code.

Structure

When implementing new features it is important to keep the conceptual integrity of the service by applying the: TDD, SOLID, practices and following the Clean Code philosophy.

In order to make it easy to understand and extend the codebase, the folder structure mirrors the project architecure:

api-seed
├── infrastructure          // Infrastructure as code (e.g. Docker)
│   └── containerization    // Example of Docker image
├── src                     // Production code and associated unit tests
│   ├── main                // Main layer
│   ├── delivery            // Delivery layer
│   ├── shared              // Shared functionalities between layers (e.g. Logging)
│   ├── repository          // Adapters layers (e.g. Repositories or Services)
│   └── domain              // Domain layer. It is agnostic of the way it's deployed
│       ├── boundaries      // Boundaraires to the external dependencies.
│       ├── entities        // Entities to the external dependencies.
│       └── usecases        // Busines logic. 
└── tests                   // Testing code
    ├── reports             // Generated reports
    └── e2e                 // End-2-end testing