From 9fe4ea478d22d7dfb2638eee8a8b2246f90af002 Mon Sep 17 00:00:00 2001 From: "Kali Kaneko (leap communications)" Date: Mon, 12 Dec 2016 01:43:51 +0100 Subject: [refactor] reorganize API so that whitelisting doesn't have to peek into the data. added more documentation and some tests stubs too. --- docs/core/core_api_contract | 2 + docs/core/index.rst | 228 +++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 226 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/core/core_api_contract b/docs/core/core_api_contract index b70fb8f..ba4a963 100755 --- a/docs/core/core_api_contract +++ b/docs/core/core_api_contract @@ -21,6 +21,8 @@ api for Bitmask Core. The values are meant to be type annotations. """ +import pkg_resources +pkg_resources.get_distribution('leap.bitmask') if __name__ == "__main__": from leap.bitmask.core.service import BitmaskBackend diff --git a/docs/core/index.rst b/docs/core/index.rst index c52dcc1..9740744 100644 --- a/docs/core/index.rst +++ b/docs/core/index.rst @@ -4,10 +4,230 @@ .. _bitmask_core: +============ Bitmask Core -================================ -blah blah +============ -API documentation --------------------------------- +The bitmask core daemon can be launched like this:: + bitmaskd + +The command-line program, ``bitmaskctl``, and the GUI, will launch the +daemon when needed. + +Starting the API server +======================= + +If configured to do so, the bitmask core will expose all of the commands +throught a REST API. In bitmaskd.cfg:: + + [services] + web = True + + +Resources +========= + +Following is a list of currently available resources and a brief description of +each one. For details click on the resource name. + ++-----------------------------------+---------------------------------+ +| Resource | Description | ++===================================+=================================+ +| ``POST`` :ref:`cmd_core_version` | Get Bitmask Core Version Info | ++-----------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_core_stats` | Get Stats about Bitmask Usage | ++-----------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_core_status` | Get Bitmask Status | ++-----------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_core_stop` | Stop Bitmask Core | ++-----------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_prov_list` | List all providers | ++-----------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_prov_create` | Create a new provider | ++-----------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_prov_read` | Get info about a provider | ++-----------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_prov_del` | Delete a given provider | ++-----------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_user_list` | List all users | ++-----------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_user_active` | Get active user | ++-----------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_user_create` | Create a new user | ++-----------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_user_update` | Update an user | ++-----------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_user_auth` | Authenticate an user | ++-----------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_user_logout` | End session for an user | ++-----------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_keys_list` | Get all known keys for an user | ++-----------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_keys_insert` | Insert a new key | ++-----------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_keys_del` | Delete a given key | ++-----------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_keys_export` | Export keys | ++-----------------------------------+---------------------------------+ + +.. _cmd_core_version: + +/core/version +------------- +**POST /core/version** + + Get Bitmask Core Version Info + +.. _cmd_core_stats: + +/core/stats +----------- +**POST /core/stats** + + Get Stats about Bitmask Usage + +.. _cmd_core_status: + +/core/status +------------ +**POST /core/status** + + Get Bitmask status + +.. _cmd_core_stop: + +/core/stop +---------- +**POST /core/stop** + + Stop Bitmask core (daemon shutdown). + +.. _cmd_prov_list: + +/bonafide/provider/list +----------------------- +**POST /bonafide/provider/list** + + List all known providers. + +.. _cmd_prov_create: + +/bonafide/provider/create +-------------------------- +**POST /bonafide/provider** + + Create a new provider. + +.. _cmd_prov_read: + +/bonafide/provider/read +----------------------- +**POST /bonafide/provider/read** + + Get info bout a given provider. + +.. _cmd_prov_del: + +/bonafide/provider/delete +------------------------- +**POST /bonafide/provider/delete** + + Delete a given provider. + + +.. _cmd_user_list: + +/bonafide/user/list +------------------- +**POST /bonafide/user/list** + + List all the users known to the local backend. + + **Form parameters**: + * ``foo`` *(required)* - foo bar. + * ``bar`` *(optional)* - foo bar. + + **Status codes**: + * ``200`` - no error + +.. _cmd_user_active: + +/bonafide/user/active +--------------------- +**POST /bonafide/user/active** + + Get the active user. + +.. _cmd_user_create: + +/bonafide/user/create +--------------------- +**POST /bonafide/user/create** + + Create a new user. + + **Form parameters**: + * ``foo`` *(required)* - foo bar. + +.. _cmd_user_update: + +/bonafide/user/update +--------------------- +**POST /bonafide/user/update** + + Update a given user. + +.. _cmd_user_auth: + +/bonafide/user/authenticate +--------------------------- +**POST /bonafide/user/authenticate** + + Authenticate an user. + +.. _cmd_user_logout: + +/bonafide/user/logout +--------------------- +**POST /bonafide/user/logout** + + Logs out an user, and destroys its local session. + +.. _cmd_keys_list: + +/keys/list +------------------- +**POST /keys/list** + + Get all keys for an user. + +.. _cmd_keys_insert: + +/keys/insert/ +------------------- +**POST /keys/insert** + + Insert a new key for an user. + +.. _cmd_keys_del: + +/keys/delete/ +------------------- +**POST /keys/delete** + + Delete a key for an user. + +.. _cmd_keys_export: + +/keys/export/ +------------------- +**POST /keys/export** + + Export keys for an user. + + +API Authentication +================== + +(TBD) Most of the resources in the API are protected by an authentication token. -- cgit v1.2.3