Service Book

Mozilla Services projects API. Provides a Database of all projects and a set of API to interact with them.

.. image:: https://img.shields.io/badge/license-MPL%202.0-blue.svg :target: https://github.com/mozilla/servicebook-web/blob/master/LICENSE.txt :alt: License .. image:: https://img.shields.io/circleci/project/github/mozilla/servicebook/master.svg?logo=circleci :alt: CircleCI :target: https://circleci.com/gh/mozilla/servicebook/tree/master .. image:: https://img.shields.io/travis/mozilla/servicebook/master.svg?logo=travis :target: https://travis-ci.org/mozilla/servicebook :alt: Travis CI .. image:: https://img.shields.io/coveralls/github/mozilla/servicebook/master.svg :alt: Coverage :target: https://coveralls.io/github/mozilla/servicebook?branch=master .. image:: https://api.dependabot.com/badges/status?host=github&repo=mozilla/servicebook :target: https://dependabot.com :alt: Dependabot

Use the Service Book

The Service Book provides a RESTFul HTTP API. If you are using Python, you can use the restjson client: https://github.com/tarekziade/restjson

It provides a simple tool to interact with the Service Book.

Running locally

The servicebook uses a MySQL database by default, but you can use SQLITE3 or postgres by tweaking the sqluri option in servicebook.ini.

Create a local virtualenv, install requirements, initialize the DB then run the service::

$ pipenv install --dev
$ pipenv shell
$ servicebook-import --sqluri mysql+pymysql://book:book@0.0.0.0/book
$ servicebook

The app runs on the 5001 port by default.

Running with Docker

You can run the app using the provided Dockerfile, by building the docker image, then running it. It will bind the app to your 5001 port::

$ make docker-build
$ make docker-run

The Docker image will reach out for the database that's set servicebook.ini.

Running with external DB

If you would like to use an external DB for storage, be sure to set the default character set for the database to UTF-8 (utf8mr for mysql).

Authentication

The application can secure the HTTP API access for reads and/or writes.

You can define how anonymous accesses are handled with the anonymous_access variable in the common section of the config file.

The value to set is a permission scope. Possible values:

read: access to GET and HEAD calls - default value when non specified
readwrite: access to PATCH, PUT, POST, DELETE, GET, HEAD
admin: like readwrite - will be used for specific admin tasks

Client can also have a privileged access with an API key. The key is passed in the Authorization header, prefixed by APIKey::

Authorization APIKey ZGJkYWI3ZmQtZDEwNy00MzJiLWJlNDgtMjZkNTQyZGFiZDhi

The value is a base64-encoded UUID. Each application that wishes to get a privileged access should have its own API key and scope.

You can list/add/revoke keys using the servicebook-keys command::

$ servicebook-keys --sqluri mysql+pymysql://book:book@0.0.0.0/book list
No keys!

$ servicebook-keys --sqluri mysql+pymysql://book:book@0.0.0.0/book add MyApp
App: MyApp, Key: 399c1365-3700-4ce6-8fd1-f304a32a0794, Scope: read

$ servicebook-keys --sqluri mysql+pymysql://book:book@0.0.0.0/book add MyApp2 --scope readwrite
App: MyApp2, Key: e87271fd-ca31-46cf-8cc5-48b1f9348e4e, Scope: readwrite

$ servicebook-keys --sqluri mysql+pymysql://book:book@0.0.0.0/book list
App: MyApp, Key: 399c1365-3700-4ce6-8fd1-f304a32a0794, Scope: read
App: MyApp2, Key: e87271fd-ca31-46cf-8cc5-48b1f9348e4e, Scope: readwrite

$ servicebook-keys --sqluri mysql+pymysql://book:book@0.0.0.0/book revoke MyApp
Key revoked for MyApp

$ servicebook-keys --sqluri mysql+pymysql://book:book@0.0.0.0/book list
App: MyApp2, Key: e87271fd-ca31-46cf-8cc5-48b1f9348e4e, Scope: readwrite

The default setup will make the data read-only and will require a privileged access with readwrite scope for writing in the database.

You should have one separate key per calling service so it's easier to revoke or renew a specific service access if required.