Setting up a service using kinto.core

The magical way to build an HTTP microservice

What is kinto.core?

kinto.core is a toolkit to ease the implementation of HTTP microservices. It is mainly focused on data-driven REST APIs (aka CRUD). kinto.core is in fact a step towards producing standardized APIs, which follow some well known patterns, encouraging genericity in clients code. The best part is that it can be extended and customized in many ways. It can also be used in any kind of project, for its tooling, utilities and helpers.

What features does kinto.core bring with it?

kinto.core exposes a well defined HTTP REST API with endpoints that are based around the concept of resources.

• It facilitates collection and records manipulation
• Handles the HTTP status and headers
• Looks after the API versioning and deprecation
• Gives you the freedom of error formatting
• Provides optional validation from schema
• Lets you sort and filter records
• Provides pagination using continuation tokens
• Polling for changes in collections and synchronization of a collection of records.
• Record race conditions handling using preconditions headers;
• Notifications channel (e.g. run asynchronous tasks on changes).

Of course you can add the desired endpoints but there are some generic endpoints that come with every kinto.core project:

• Hello view at root url — /
• Heartbeat for monitoring — /__heartbeat__
• Batch operations — /batch

What else?

You can configure the project using environment variables or using INI files. There’s the option to plug-in desired storage and cache backends (e.g.: postgresql or redis ). There are also pluggable authentication and user groups management, pluggable authorization and permissions management, structured logging to, monitoring and profiling tools.

What is it built of?

• Cornice for the schema validation, REST and CORS helpers
• Pyramid for configuration, HTTP request and response handling
• SQLAlchemy core for database transaction session and connections pooling

Everything else is meant to be pluggable and optional.

Basic Auth, FxA OAuth2 or any other source of authentication, Default or custom class for authorization logics, PostgreSQL for storage, Redis for key-value cache with expiration, StatsD metrics, Sentry reporting via logging, NewRelic database profiling , NewRelic database profiling, Werkzeug Python code profiling

How to setup a service using kinto.core?

Creating your setup.py :

The service module directory:

Add the __init__.py to the directory.

This will enable the WSGI middleware:

app = config.make_wsgi_app()
return kinto.core.install_middlewares(app, settings)

Add the views directory to your module directory. This will contain the endpoints for your service.

Next, we’ll need to work on our config.ini. It specifies the app, WSGI server and logging configurations. Here’s a sample:

In the views directory, to add an endpoint, say, food which fetches information about your favorite food items.

@register does the job of registering the endpoint with the cornice registry.

Colander helps define the schema for the endpoint resource. It also validates the schema, and can serialize as well as deserialize structures.

Here in this example, I have defined the food endpoint to be a UserResource which is the base resource class for endpoints in kinto.core. You can also define an endpoint as a ShareableResource — it allows to set permissions on records, in order to share their access or protect their modification. When using UserResource, every authenticated user can manipulate and read their own records. There is no way to restrict this or allow sharing of records whereas with ShareableResource, kinto.core will register the endpoints with a specific route factory, that will take care of checking the appropriate permission for each action.

The file structure will look somewhat like this:

<your service package name>/
├── docs
├── <your module name>
│   ├── __init__.py
│   ├── views
│    ├── __init__.py
│    ├── <your endpoint>.py  
│ 
├── config.ini
├── requirements.txt
├── LICENSE
├── Makefile
├── README.rst
└── setup.py

You can also write tests for your endpoints in a tests directory. You can use unittest to write the tests.

For the food endpoint I created above, sample requests sent to the server would return the following responses (I’ll be using httpie for sending the HTTP request):

Sample request:

$ echo '{"data": {"food": "chocolate", "taste": "varies from bitter to sweet"}}' | http post http://localhost:9999/v0/food --auth "token:mkaur"

Sample Response:

HTTP/1.1 201 Created
Access-Control-Expose-Headers: Retry-After, Content-Length, Alert, Backoff
Content-Length: 109
Content-Type: application/json
Date: Sun, 29 Jan 2017 13:05:03 GMT
Etag: "1485695103995"
Last-Modified: Sun, 29 Jan 2017 13:05:03 GMT
Server: waitress
X-Content-Type-Options: nosniff

{
    "data": {
        "food": "chocolate",
        "id": "6a805435-84e9-4311-8196-63614cf6b455",
        "taste": "varies from bitter to sweet",
        "last_modified": 1485695103995
    }
}

Here’s a test (test_food_post_returns_correct_response) to validate the response generated above:

Good luck creating your first service with kinto.core and if you need any help or just want to say hi!, please join our irc channel — #kinto on irc.freenode.net or if you prefer to use slack — https://slack.kinto-storage.org/