sqre-apikit


Namesqre-apikit JSON
Version 0.1.2 PyPI version JSON
download
home_pagehttps://github.com/lsst-sqre/sqre-apikit
SummaryLSST Data Management SQuaRE microservice tools
upload_time2017-10-19 23:12:22
maintainer
docs_urlNone
authorAdam Thornton
requires_python
licenseMIT
keywords lsst
VCS
bugtrack_url
requirements None
Travis-CI
coveralls test coverage No coveralls.
            [![Build Status](https://travis-ci.org/lsst-sqre/sqre-apikit.svg?branch=master)](https://travis-ci.org/lsst-sqre/sqre-apikit)

# sqre-apikit

LSST DM SQuaRE microservice convenience tools.

## Rationale

In order to create a microservice hosted behind https://api.lsst.codes,
a service will need to provide a route on `/metadata` and
`/v{{api_version}}/metadata`.  That route must serve appropriate
metadata about the service.

### Metadata format

The metadata served must be a JSON object, and must contain the
following fields: 

`name`: `str`

`version`: `str`

`repository`: `str`

`description`: `str`

`api_version`: `str`

`auth`: `str`

The fields `name`, `version`, `api_version`, and `description` are
arbitrary, although semantic versioning is strongly encouraged, and the
API version should reflect the version of the `api.lsst.codes` API in
use (currently `1.0`, documentation pending).

Auth must be one of `none`, `basic`, or `bitly-proxy`.  It represents
the way in which the microservice will authenticate to GitHub: either it
doesn't need to, it uses HTTP Basic Auth with a username and service
token, or it uses the Bitly OAuth2 Proxy with a username, a password,
and the proxy starting-OAuth2 endpoint.

## Provided Functionality

`sqre-apikit` provides one module, `apikit`, which contains three
functions, `set_flask_metadata`, `add_metadata_route`, and
`return_metadata`, and a class, `APIFlask`.

The `set_flask_metadata` sets metadata on an existing Flask app and adds
metadata routes.  `add_metadata_route` is designed to add routing for
each component in the route list to an existing Flask app.
`return_metadata` returns the JSON representation of the metadata for
the service.

The `APIFlask` class creates an instance of a subclass of `flask.Flask`
which has the metadata added and the route(s) already baked into it.

The class comes with a method, `add_route_prefix`, which adds the
metadata route underneath another route.  This is useful, for instance,
if wiring the microservice up through Kubernetes and its Ingress
resources, which provide routing but not rewriting.

## Installation

`sqre-apikit` runs on Python 2.7 or 3.5. You can install it with

```bash
pip install sqre-apikit
```

This will also install the dependency `Flask`.

## Example usage

### `apikit.set_flask_metadata()`

```python
import apikit
import flask

app = flask.Flask("Hello")
apikit.set_flask_metadata(app,
                          version="0.0.1",
                          repository="http://example.repo",
                          description="Hello World App")
```

### `apikit.APIFlask`

```python
import apikit

app = apikit.APIFlask(name="Hello",
                      version="0.0.1",
                      repository="http://example.repo",
                      description="Hello World App")
```

## Development

To develop apikit, create a Python virtual environment, and

```bash
git clone https://github.com/lsst-sqre/sqre-apikit.git
cd sqre-apikit
virtualenv venv
. venv/bin/activate
pip install -r requirements.txt
python setup.py develop
```
Tests can be run with [pytest](http://pytest.org/latest/):

```bash
py.test tests
```



            

Raw data

            {
    "_id": null,
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "cheesecake_code_kwalitee_id": null,
    "keywords": "lsst",
    "upload_time": "2017-10-19 23:12:22",
    "requirements": [
        {
            "name": null,
            "specs": []
        }
    ],
    "author": "Adam Thornton",
    "home_page": "https://github.com/lsst-sqre/sqre-apikit",
    "github_user": "lsst-sqre",
    "download_url": "https://pypi.python.org/packages/d3/fb/3c03ce894a3db4e950764c413135a6cd2b662f4076ca383952afaf494bc8/sqre-apikit-0.1.2.tar.gz",
    "platform": "",
    "version": "0.1.2",
    "cheesecake_documentation_id": null,
    "description": "[![Build Status](https://travis-ci.org/lsst-sqre/sqre-apikit.svg?branch=master)](https://travis-ci.org/lsst-sqre/sqre-apikit)\n\n# sqre-apikit\n\nLSST DM SQuaRE microservice convenience tools.\n\n## Rationale\n\nIn order to create a microservice hosted behind https://api.lsst.codes,\na service will need to provide a route on `/metadata` and\n`/v{{api_version}}/metadata`.  That route must serve appropriate\nmetadata about the service.\n\n### Metadata format\n\nThe metadata served must be a JSON object, and must contain the\nfollowing fields: \n\n`name`: `str`\n\n`version`: `str`\n\n`repository`: `str`\n\n`description`: `str`\n\n`api_version`: `str`\n\n`auth`: `str`\n\nThe fields `name`, `version`, `api_version`, and `description` are\narbitrary, although semantic versioning is strongly encouraged, and the\nAPI version should reflect the version of the `api.lsst.codes` API in\nuse (currently `1.0`, documentation pending).\n\nAuth must be one of `none`, `basic`, or `bitly-proxy`.  It represents\nthe way in which the microservice will authenticate to GitHub: either it\ndoesn't need to, it uses HTTP Basic Auth with a username and service\ntoken, or it uses the Bitly OAuth2 Proxy with a username, a password,\nand the proxy starting-OAuth2 endpoint.\n\n## Provided Functionality\n\n`sqre-apikit` provides one module, `apikit`, which contains three\nfunctions, `set_flask_metadata`, `add_metadata_route`, and\n`return_metadata`, and a class, `APIFlask`.\n\nThe `set_flask_metadata` sets metadata on an existing Flask app and adds\nmetadata routes.  `add_metadata_route` is designed to add routing for\neach component in the route list to an existing Flask app.\n`return_metadata` returns the JSON representation of the metadata for\nthe service.\n\nThe `APIFlask` class creates an instance of a subclass of `flask.Flask`\nwhich has the metadata added and the route(s) already baked into it.\n\nThe class comes with a method, `add_route_prefix`, which adds the\nmetadata route underneath another route.  This is useful, for instance,\nif wiring the microservice up through Kubernetes and its Ingress\nresources, which provide routing but not rewriting.\n\n## Installation\n\n`sqre-apikit` runs on Python 2.7 or 3.5. You can install it with\n\n```bash\npip install sqre-apikit\n```\n\nThis will also install the dependency `Flask`.\n\n## Example usage\n\n### `apikit.set_flask_metadata()`\n\n```python\nimport apikit\nimport flask\n\napp = flask.Flask(\"Hello\")\napikit.set_flask_metadata(app,\n                          version=\"0.0.1\",\n                          repository=\"http://example.repo\",\n                          description=\"Hello World App\")\n```\n\n### `apikit.APIFlask`\n\n```python\nimport apikit\n\napp = apikit.APIFlask(name=\"Hello\",\n                      version=\"0.0.1\",\n                      repository=\"http://example.repo\",\n                      description=\"Hello World App\")\n```\n\n## Development\n\nTo develop apikit, create a Python virtual environment, and\n\n```bash\ngit clone https://github.com/lsst-sqre/sqre-apikit.git\ncd sqre-apikit\nvirtualenv venv\n. venv/bin/activate\npip install -r requirements.txt\npython setup.py develop\n```\nTests can be run with [pytest](http://pytest.org/latest/):\n\n```bash\npy.test tests\n```\n\n\n",
    "lcname": "sqre-apikit",
    "name": "sqre-apikit",
    "github": true,
    "coveralls": false,
    "bugtrack_url": null,
    "license": "MIT",
    "travis_ci": true,
    "github_project": "sqre-apikit",
    "summary": "LSST Data Management SQuaRE microservice tools",
    "split_keywords": [
        "lsst"
    ],
    "author_email": "athornton@lsst.org",
    "urls": [
        {
            "has_sig": false,
            "upload_time": "2017-10-19T23:12:22",
            "comment_text": "",
            "python_version": "source",
            "url": "https://pypi.python.org/packages/d3/fb/3c03ce894a3db4e950764c413135a6cd2b662f4076ca383952afaf494bc8/sqre-apikit-0.1.2.tar.gz",
            "md5_digest": "d20fea32a30817a1c38d54ae1d9d8ea1",
            "downloads": 0,
            "filename": "sqre-apikit-0.1.2.tar.gz",
            "packagetype": "sdist",
            "path": "d3/fb/3c03ce894a3db4e950764c413135a6cd2b662f4076ca383952afaf494bc8/sqre-apikit-0.1.2.tar.gz",
            "size": 8950
        },
        {
            "has_sig": false,
            "upload_time": "2017-10-19T23:12:21",
            "comment_text": "",
            "python_version": "py3",
            "url": "https://pypi.python.org/packages/f8/3f/4f4ab11fa1baf8d922d5f763c814fd2c5e71d222c9f14b70a6e66361f806/sqre_apikit-0.1.2-py3-none-any.whl",
            "md5_digest": "77554041223b54514fd3bcf5368d95d0",
            "downloads": 0,
            "filename": "sqre_apikit-0.1.2-py3-none-any.whl",
            "packagetype": "bdist_wheel",
            "path": "f8/3f/4f4ab11fa1baf8d922d5f763c814fd2c5e71d222c9f14b70a6e66361f806/sqre_apikit-0.1.2-py3-none-any.whl",
            "size": 10709
        }
    ],
    "cheesecake_installability_id": null
}
        
Elapsed time: 0.08297s