README.md

GraphQL API Gateway

This project is an example of GraphQL implementation for API Gateway that can interact with microservices.

Requirements:

Install the appropriate software:

1. Docker Desktop.
2. Git.
3. PyCharm (optional).

Installation

Clone the repository to your computer:

git clone https://github.com/mnv/python-course-graphql-gateway

1. To configure the application copy .env.sample into .env file:

   cp .env.sample .env

   This file contains environment variables that will share their values across the application. The sample file (.env.sample) contains a set of variables with default values. So it can be configured depending on the environment.

2. Build the container using Docker Compose:

   docker compose build

   This command should be run from the root directory where Dockerfile is located. You also need to build the docker container again in case if you have updated requirements.txt.

3. To run the project inside the Docker container:

   docker compose up

   When containers are up server starts at http://127.0.0.1:8000/graphql. You can open it in your browser.

Usage

Queries

This project provides fixtures to test GraphQL. Fixtures are located in src/fixtures. There are JSON-files for favorite places and countries information. GraphQL application uses these fixtures to emulate REST API responses.

Query example to request a list of favorite places:

query {
  places {
    latitude
    longitude
    description
    city
    locality
  }
}

Query example to request a list of favorite places with countries information:

query {
  places {
    latitude
    longitude
    description
    city
    locality
    country {
      name
      capital
      alpha2code
      alpha3code
      capital
      region
      subregion
      population
      latitude
      longitude
      demonym
      area
      numericCode
      flag
      currencies
      languages
    }
  }
}

This query will request additional information about related countries in optimal way using data loaders to prevent N + 1 requests problem.

Automation commands

The project contains a special Makefile that provides shortcuts for a set of commands:

1. Build the Docker container:

   make build

2. Generate Sphinx documentation run:

   make docs-html

3. Autoformat source code:

   make format

4. Static analysis (linters):

   make lint

5. Autotests:

   make test

   The test coverage report will be located at src/htmlcov/index.html. So you can estimate the quality of automated test coverage.

6. Run autoformat, linters and tests in one command:

   make all

Run these commands from the source directory where Makefile is located.

Documentation

The project integrated with the Sphinx documentation engine. It allows the creation of documentation from source code. So the source code should contain docstrings in reStructuredText format.

To create HTML documentation run this command from the source directory where Makefile is located:

make docs-html

After generation documentation can be opened from a file docs/build/html/index.html.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT