Rationale

Kinto-Core is a toolkit to ease the implementation of HTTP microservices. It is mainly focused on data-driven REST APIs (aka CRUD).

Philosophy

  • KISS;
  • No magic;
  • Works with defaults;
  • Easy customization;
  • Straightforward component substitution.

Kinto-Core doesn’t try to be a framework: any project built with Kinto-Core will expose a well defined HTTP API for:

  • Collection and records manipulation;
  • HTTP status and headers handling;
  • API versioning and deprecation;
  • Errors formatting.

This HTTP API is an implementation of a series of good practices (followed at Mozilla Services and elsewhere).

The goal is to produce standardized APIs, which follow some well known patterns, encouraging genericity in clients code [1].

Of course, Kinto-Core can be extended and customized in many ways. It can also be used in any kind of project, for its tooling, utilities and helpers.

Features

It is built around the notion of resources: resources are defined by sub-classing, and Kinto-Core brings up the HTTP endpoints automatically.

Records and synchronization

  • Collection of records by user;
  • Optional validation from schema;
  • Sorting and filtering;
  • Pagination using continuation tokens;
  • Polling for collection changes;
  • Record race conditions handling using preconditions headers;
  • Notifications channel (e.g. run asynchronous tasks on changes).

Generic endpoints

  • Hello view at root url;
  • Heartbeat for monitoring;
  • Batch operations;
  • API versioning and deprecation;
  • Errors formatting;
  • Backoff and Retry-After headers.

Toolkit

../_images/cliquet-base.png

Kinto-Core brings a set of simple but essential features to build APIs.

  • Configuration through INI files or environment variables;
  • Pluggable storage and cache backends;
  • Pluggable authentication and user groups management;
  • Pluggable authorization and permissions management;
  • Structured logging;
  • Monitoring tools;
  • Profiling tools.

Pluggable components can be replaced by another one via configuration.

Dependencies

Kinto-Core is built on the shoulders of giants:

Everything else is meant to be pluggable and optional.

../_images/cliquet-mozilla.png

Examples of configuration for a Kinto-Core application in production.

  • 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 (for development);
  • Werkzeug Python code profiling (for development).

A Kinto-Core application can change or force default values for any setting.

Built with Kinto-Core

Some applications in the wild built with Kinto-Core:

  • Reading List, a service to synchronize articles between devices;
  • Kinto, a service to store and synchronize schema-less data.
  • Syncto, a service to access Firefox Sync using kinto.js.
  • Please contact us to add yours.

Any application built with Kinto-Core:

  • follows the same conventions regarding the HTTP API;
  • takes advantage of its component pluggability;
  • can be extended using custom code or Pyramid external packages;

Similar projects

  • Python Eve, built on Flask and MongoDB;
  • Please contact us to add more if any.

Since the HTTP API is language independant and follows good HTTP/REST principles, in the long term Kinto-Core should become only one among several server implementations.

Note

We encourage you to implement a clone of this project — using Node.js, Asyncio, Go, Twisted, Django or anything else — following the same HTTP API!

[1]Switch from custom API to JSON-API spec is being discussed.