ct-core-api 2.1.0b0

Getting Started

This is how to create and register an API in your project:

"""catalant/example/app/__init__.py"""

from ct_core_api.api import core
from ct_core_api.api.app import create_api_app

# TODO: Revise this example for 2.0

Here is what your application’s main entry point should look like:

"""catalant/example/app/main.py"""

#!/usr/bin/env python

from catalant.example.app import create_example_api_app


app = create_example_api_app()


if __name__ == '__main__':
    from ct_core_api.api.app import runner
    runner.run(app)

Structuring the entry point as such allows us to invoke and run the Flask application as an executable script, directly using Flask’s development server, or using a uwsgi web server.

Changelog

Every API application has it’s own changelog. Developers are expected to update the changelog anytime a functional or structural change to the API occurs.

“Keep a CHANGELOG” has a good set of guiding principles for when and how a changelog should be maintained.

By default, the API’s changelog is accessible at /changelog and the entries live in changelog.yml in the application’s root folder (APIApp.root_path).

You can modify the path to this file using the API_CHANGELOG_PATH config setting.

---                                            # Separate changelog entries by date
<yyyy-mm-dd>:                                  # The current date
  <added|changed|removed|deprecated>:          # The type of change
    - type: <operation|parameter|model|enum>:  # What kind of thing changed
      id: <identifier>                         # The changed thing's identifier
      [note]: <note>                           # An optional, human-friendly note of what changed

Package Layout

The packages in this repository are carefully organized to avoid circular imports and to maintain the proper separation of concerns. It’s safe to import and use modules from packages as long as they don’t violate the ordering described below:

• ct_core_api.common

• ct_core_api.core

• ct_core_api.api.lib

• ct_core_api.api.common

• ct_core_api.api.core

• ct_core_api.api.app

Your module can reference other modules in the same package or in packages at the same level or higher according to this list. For example, a module in ct_core_api.api.core can depend on one from ct_core_api.api.common but not on one from ct_core_api.api.app.

Smoke Testing

Here’s how you can run the dummy application to verify the basic functioning of the core API and web application:

Executable Python script:

export PYTHONPATH=$PYTHONPATH:`pwd`
./ct_core_api/_main.py

Flask development server:

export FLASK_APP=ct_core_api/_main.py
export FLASK_DEBUG=1
export FLASK_CONFIG=development
flask run