GitHub - lechatquidanse/bicing-api: Get statistics and locations of bicycle stat...

README.md

Bicing Statistics API

Symfony 4 REST API applying CQRS and DDD patterns, built with CI, driven by BDD.

Get statistics and locations of bicycle stations.

The goal of this REST API is to ease customer's usage of large-scale public bicycle sharing system.
By collecting data from different providers (Bicing, Velib, ...) it gives powerful information (location to pick or return a bike, best time for picking up a bike, ...).
Here is an example of a user interface project calling the API /lechatquidanse/bicing-user-interface-app

Getting Started • Features • Built With • Development • Coding Standard • CI and Deployment

Getting Started

Prerequisites

To install and run the API you need Docker Compose and... that's all. Please follow the official documentation to install it on your environment.

Installing

Clone the project and run the default installation:

git clone https://github.com/lechatquidanse/bicing-api.git && cd bicing-api && make install

Your docker containers should have been successfully built and run.

Features

Multiple features are proposed across 2 user interfaces, a REST API and command-line commands:

REST API:

You can find the concrete user stories written in Gherkin in features folder. These behaviour requirements are tested with Behat.

CLI:

To run the project once installed:

Built with

• PHP 7.2
• Symfony 4.1
• API-Platform
• Timescale Database
• Docker

Development

The Makefile contains useful command for development purpose

Coding standard

Domain Driven Design

Code and folder structure follow Domain Driven Design (DDD).
Here is a good article to understand naming and folder Domain Driver Design, little explanation and example.

src
    \
        |\ Application     `Contains the Use Cases and the Processes of the domain system, commands, handlers and subscribers`
        |
        |\ Domain          `The system business logic layer (Models, Events, Exceptions...)`
        |
        |\ Infrastructure  `Its the implementation of the system outside the model. I.E: Persistence, Query, etc`
        |
        |\ UserInterface   `It contains all the interfaces allowed for a user of the API (Cli, HTTP, Rest, etc)`

Command Query Responsibility Segregation

In this project, a use case is a command or a query with a single responsibility. This use case is then handled by a handler for a command or a data provider for a query.

Commands are handled by a message bus (SimpleBus) where a command is link to one handler.
For example, to create a station in database:

CI and Deployment

CI and deployment can be handled through Gitlab and Docker thanks to .gitlab-ci.yml It contains 3 different stages.

Test

Environment 'test' is triggered when a 'feature/*' branch is pushed to the repository. It will then install project and launch qa tools.

Build

Environment 'build' is triggered when a 'release/*' branch is pushed to the repository. It will then install project, launch qa tools and then build and push a docker image on a registry if no error occured.

Production

This manual action, will pull the image build by the previous step and update the specific container.

License

MIT

Stéphane EL MANOUNI  ·  Linkedin