Ablator is a Functionality-Switching-Service that makes it easy for your app to roll out new features in a controlled way, and to perform reliable A/B testing.

.. image:: ablator/web_admin/static/ablator/ablator_logo.png :align: center

It works like this:

1. You define your app's switchable functionalities in ablator.
2. Your app asks ablator "User X wants Functionality Y. Which Flavor should I show them, if any?"
3. ablator takes care of slowly rolling out the feature in a way that you define.

As an administrator, you'll get a nice overview of what percentage of users has a functionality enabled.

.. figure:: docs/screenshot.png :alt: Screen shot showing the percentage of enabled users for a functionality

At the moment, ablator is in an early stage of development. The core APIs are completely available, and there is a custom user interface to manage day-to-day operations. There is also a Docker file available, so you can deploy it yourself.

See the road map_ for a list of features that are planned for the future.

.. _road map: docs/roadmap.rst

For an in-depth explanation of the logical parts of ablator, see the models description_.

.. _models description: docs/models.rst

Accessing the Ablator API

To identify your user, ablator needs a *client user string* of your choice.
This can be any string that identifies your users between launches of your app,
e.g. a user ID, an email address, etc. It will be hashed before being saved to the ablator
database, so even someone with full database access won't be able to reproduce the user
identifier.

To identify you App, you need to go to ablator's web interface, and retrieve the app's ID,
represented as a long hex string or UUID.

You need these two pieces of information, a client user string and an App ID, to interact
with ablator's Web API. The following is the commplete definiton of ablator's public API:

https://ablator.space/api/v3/<client_user_string>/<app_id>/caniuse/
    Returns a list of enabled functionalities of the specified app. Functionalities that
    are not enabled are not shown. You can use this API endpoint if you expect a functionality
    which is only switched on or off using ablator.

https://ablator.space/api/v3/<client_user_string>/<app_id>/flavors/
    Returns a list of enabled Flavors of the specified app. Flavors that are not enabled are
    not shown. Unlike Functionalities, Flavors represent a specific *variant* of a feature. If
    you use Flavors for A/B testing or something similar, this is where your data comes from.

https://ablator.space/api/v3/<client_user_string>/<app_id>/tag/
    Returns a list of tags that are applied to the specified user. Tags allow you to segment
    and manage your user base, and enable or disable certain functionalities based on tags.

It is recommended you use client libraries instead of accessing the API yourself. Currently
there are are libraries for `swift`_, `python`_, and `javascript`_ available.

.. _python: https://github.com/ablator/karman
.. _swift: https://github.com/ablator/shepard
.. _javascript: https://github.com/ablator/herschel

Branches
--------

If you want a tested, working, released version of Ablator, check out the :code:`release` 
branch. The current stable development version is in the :code:`stable` branch. Unstable 
feature branches are prefixed with :code:`feature/`. 

Help Out and Code of Conduct
----------------------------

We'd like to encourage your feature requests, bug reports and pull requests. Please note that a
Code of Conduct as described in `CODE_OF_CONDUCT.md` applies to this project. In short, be friendly,
welcoming, considerate, respectful, and be careful in the words that you choose please. If you think
you've witnessed a CoC violation, please contact Daniel at [email protected] .