=====================
Delphi SLZ API README
=====================

The Delphi API, a.k.a. The Enablements API.

:Release:
    .. image:: https://img.shields.io/badge/release-v1.2-blue.svg?style=flat-square

:Maintained by:
    Sony Music - Data & Analytics – Delphi Team


Workflow
--------

This repo's Git workflow follows `Github Flow`_.

  .. _Github Flow: https://guides.github.com/introduction/flow/

1. Create a branch off of `master`
2. Commit and push your branch code
3. Open a pull request on Github for code review and QA testing

If another pull request has been merged into master before yours, it is preferable to **rebase** your branch,
and force push your changes. If multiple developers are working on a shared branch however, merging master
into your branch makes more sense.

Here are two ways to rebase your branch's code (optionally ``-i`` for interactive):

  .. code-block:: bash

    git checkout <yourbranch>
    git fetch origin master
    git rebase -i origin/master

Alternatively, This method checks out master and pulls, but requires extra steps:

  .. code-block:: bash

    git checkout master
    git pull
    git checkout <yourbranch>
    git rebase -i master

With **PyCharm**, the process is the most straightforward:

1. Checkout ``master`` branch and pull the latest
2. Click on your branch from the Git list in the bottom toolbar, and select
   "Checkout and Rebase onto Current"
3. Force push your branch to the remote


Principles
----------

Design principles are based on:

- `Google's API Design Guide`_
- `API First Design`_
- `OpenAPI v3 Specification`_

  .. _Google's API Design Guide: https://cloud.google.com/apis/design/
  .. _API First Design: https://swagger.io/resources/articles/adopting-an-api-first-approach/
  .. _OpenAPI v3 Specification: https://swagger.io/specification/


Features
--------

- The Connexion_ Framework on top of Flask
- Pythonic DynamoDB library PynamoDB_

  .. _Connexion: https://connexion.readthedocs.io/en/latest/index.html
  .. _Flask: http://flask.palletsprojects.com/en/1.1.x/
  .. _PynamoDB: https://github.com/pynamodb/PynamoDB


Useful make Commands
--------------------
- ``make venv`` - create local virtual env (``requirements.txt`` dependencies)
- ``make devenv`` - create local virtual env (``requirements/dev.pip`` dependencies)
- ``make clean`` - clean unnecessary files
- ``make docker/login`` - aws configuration need to be set first
- ``make docker/build`` - build api Docker images from a Dockerfile
- ``make docker/push`` - push an image to a registry
- ``make docs`` - build the HTML docs using Sphinx_
- ``make lint`` - run ``pylint`` on the codebase
- ``make sort`` - run ``isort`` on the project and test modules
- ``make frozen`` - update the frozen ``requirements.txt`` file based on the ``base/requirements.pip``
  file's flexible version specifications


Configuring Your AWS Credentials
--------------------------------
You'll want to have the AWS CLI installed on your machine.

To install the AWS CLI:

  .. code-block:: bash

    brew install awscli

If you have the CLI installed, you can:

- Check if your aws configuration is already set by running ``aws configure list``
- Create a new configuration with ``aws configure``
- See the `AWS CLI docs`_

  .. _AWS CLI docs: https://docs.aws.amazon.com/en_us/cli/latest/userguide/cli-chap-configure.html


Running the Container Locally
---------------------------------------------
The recommended way to run the service locally is by using ``docker-compose``.

If you do not have ``docker-compose`` installed, you can install it using homebrew:

  .. code-block:: bash

    brew install docker-compose


Build and run the container:

  .. code-block:: bash

    docker-compose build
    docker-compose up -d slz-api

Check the service is accessible at http://127.0.0.1:8000/v1/ui


Running the Test Container
--------------------------
The unit tests are run in a separate container for the test build step in Jenkins. To run this
container locally, you will want to ensure you've build the base image first.

  .. code-block:: bash

    make docker/build

After you have the base image built (branch-specific), you can run the following command for
subsequent tests:


  .. code-block:: bash

    make docker/run-test


Generating Documentation
------------------------
This project's documentation from code can be automatically generated via Sphinx_.

The below assumes you have already followed the steps above in "Getting Set Up Locally".

.. _Sphinx: http://www.sphinx-doc.org/en/stable/index.html

1. Generate the stub ``.rst`` files and the HTML browser files with make from the project root:

  .. code-block:: bash

    make docs


Linting Your Code
-----------------
Run before pushing:

  .. code-block:: bash

    make sort


Checking Code Quality
---------------------
Use the pylint command to check quality of code updates:

  .. code-block:: bash

    make lint


Creating Releases
-----------------
Use bump2version_ to create a new Delphi API release.

  .. code-block:: bash

    # dry-run to see what will happen
    bump2version --verbose patch --allow-dirty --dry-run

    # update patch version
    bump2version --verbose patch

.. _bump2version: https://github.com/c4urself/bump2version