diff --git a/source/authorization.rst b/source/authorization.rst index 21d3d0f..d03b22f 100644 --- a/source/authorization.rst +++ b/source/authorization.rst @@ -25,7 +25,7 @@ and an opaque :term:`refresh token` to renew the access token. See :doc:`endpoints/auth` endpoint documentation on how you can retrieve the JWT tokens with a standard username and password user authentication. Once the token is retrieved it can be used on every request in the ``Authorization`` HTTP header this way: -.. sourcecode:: http +.. sourcecode:: text Authorization: Bearer @@ -37,7 +37,7 @@ Through :doc:`endpoints/admin` endpoint it's possible to set and retrieve an API On each request you may set the application's API KEY using the ``X-Api-Key`` HTTP header -.. sourcecode:: http +.. sourcecode:: text X-Api-Key: diff --git a/source/conf.py b/source/conf.py index 8dbb401..1ee8150 100644 --- a/source/conf.py +++ b/source/conf.py @@ -34,7 +34,6 @@ def setup(app): import sphinx_rtd_theme html_theme = 'sphinx_rtd_theme' - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # Markdown support from recommonmark.parser import CommonMarkParser @@ -91,7 +90,7 @@ def setup(app): # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = 'en' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: diff --git a/source/endpoints/admin.rst b/source/endpoints/admin.rst index a40fcba..ad57cba 100644 --- a/source/endpoints/admin.rst +++ b/source/endpoints/admin.rst @@ -1,17 +1,225 @@ Administration ``/admin`` ========================== -.. note:: +``/admin`` endpoint deals with administrative operations on current project. - This endpoint is not yet available +Managed resources by this endpoint are: +* applications +* auth providers +* asynchronous jobs +* configuration properties +* custom endpoints +* external auth links -``/admin`` endpoint deals with administrative operations on current project +Each managed resource follows the same CRUD pattern: -Managed resources by this endpoint are: +* ``POST /admin/{resource}`` create resource +* ``GET /admin/{resource}`` list resources +* ``GET /admin/{resource}/{id}`` get single resource +* ``PATCH /admin/{resource}/{id}`` modify resource +* ``DELETE /admin/{resource}/{id}`` remove resource + +Applications +------------ + +Applications are managed through ``/admin/applications``. + +Available operations are: + +* ``POST /admin/applications`` +* ``GET /admin/applications`` +* ``GET /admin/applications/{id}`` +* ``PATCH /admin/applications/{id}`` +* ``DELETE /admin/applications/{id}`` + +**Example request: create application**: + +.. sourcecode:: http + + POST /admin/applications HTTP/1.1 + Host: api.example.com + Accept: application/vnd.api+json + Content-Type: application/vnd.api+json + + { + "data": { + "type": "applications", + "attributes": { + "name": "my-very-first-app", + "description": "My first app" + } + } + } + +Auth Providers +-------------- + +Auth providers are managed through ``/admin/auth_providers``. + +Available operations are: + +* ``POST /admin/auth_providers`` +* ``GET /admin/auth_providers`` +* ``GET /admin/auth_providers/{id}`` +* ``PATCH /admin/auth_providers/{id}`` +* ``DELETE /admin/auth_providers/{id}`` + +**Example request: create auth provider**: + +.. sourcecode:: http + + POST /admin/auth_providers HTTP/1.1 + Host: api.example.com + Accept: application/vnd.api+json + Content-Type: application/vnd.api+json + + { + "data": { + "type": "auth_providers", + "attributes": { + "name": "my-provider" + } + } + } + +Async Jobs +---------- + +Asynchronous jobs are managed through ``/admin/async_jobs``. + +Available operations are: + +* ``POST /admin/async_jobs`` +* ``GET /admin/async_jobs`` +* ``GET /admin/async_jobs/{id}`` +* ``PATCH /admin/async_jobs/{id}`` +* ``DELETE /admin/async_jobs/{id}`` + +**Example request: create async job**: + +.. sourcecode:: http + + POST /admin/async_jobs HTTP/1.1 + Host: api.example.com + Accept: application/vnd.api+json + Content-Type: application/vnd.api+json + + { + "data": { + "type": "async_jobs", + "attributes": { + "service": "dummy" + } + } + } + +Configuration +------------- + +Configuration properties are managed through ``/admin/config``. + +Available operations are: + +* ``POST /admin/config`` +* ``GET /admin/config`` +* ``GET /admin/config/{id}`` +* ``PATCH /admin/config/{id}`` +* ``DELETE /admin/config/{id}`` + +**Example request: create config**: + +.. sourcecode:: http + + POST /admin/config HTTP/1.1 + Host: api.example.com + Accept: application/vnd.api+json + Content-Type: application/json + + { + "data": { + "id": "TestConf", + "type": "config", + "attributes": { + "name": "TestConf", + "content": "config content", + "context": "config-context" + } + } + } + +Endpoints +--------- + +Custom endpoints are managed through ``/admin/endpoints``. + +Available operations are: + +* ``POST /admin/endpoints`` +* ``GET /admin/endpoints`` +* ``GET /admin/endpoints/{id}`` +* ``PATCH /admin/endpoints/{id}`` +* ``DELETE /admin/endpoints/{id}`` + +**Example request: create endpoint**: + +.. sourcecode:: http + + POST /admin/endpoints HTTP/1.1 + Host: api.example.com + Accept: application/vnd.api+json + Content-Type: application/vnd.api+json + + { + "data": { + "type": "endpoints", + "attributes": { + "name": "my_endpoint", + "description": "My first endpoint" + } + } + } + +External Auth +------------- + +External auth mappings are managed through ``/admin/external_auth``. + +Available operations are: + +* ``POST /admin/external_auth`` +* ``GET /admin/external_auth`` +* ``GET /admin/external_auth/{id}`` +* ``PATCH /admin/external_auth/{id}`` +* ``DELETE /admin/external_auth/{id}`` + +**Example request: create external auth mapping**: + +.. sourcecode:: http + + POST /admin/external_auth HTTP/1.1 + Host: api.example.com + Accept: application/vnd.api+json + Content-Type: application/vnd.api+json + + { + "data": { + "type": "external_auth", + "attributes": { + "user_id": 1, + "auth_provider_id": 1, + "provider_username": "id" + } + } + } + +Response codes +-------------- + +For all admin resources, expected responses are: - * asynchronous jobs - * client applications definitions, including API KEYs management - * custom endpoints - * configuration properties +* ``201 Created`` for successful creation +* ``200 OK`` for list/get/modify operations +* ``204 No Content`` for delete operations +* ``404 Not Found`` for missing resources diff --git a/source/endpoints/folders.rst b/source/endpoints/folders.rst index 384c05a..64eacf4 100644 --- a/source/endpoints/folders.rst +++ b/source/endpoints/folders.rst @@ -373,13 +373,13 @@ You can obtain data of parent folder, for a specified subfolder, using ``GET /fo "modified": "{modifiedDate}", "path": "/{folderId}", "relation": { - "id": {relationId}, - "object_id": {relatedId}, - "parent_id": {folderId}, - "root_id": {folderId}, - "parent_node_id": {parentId}, - "tree_left": {leftId}, - "tree_right": {rightId}, + "id": "{relationId}", + "object_id": "{relatedId}", + "parent_id": "{folderId}", + "root_id": "{folderId}", + "parent_node_id": "{parentId}", + "tree_left": "{leftId}", + "tree_right": "{rightId}", "depth_level": 1, "menu": true } diff --git a/source/endpoints/model/index.rst b/source/endpoints/model/index.rst index 5943ddd..101ab31 100644 --- a/source/endpoints/model/index.rst +++ b/source/endpoints/model/index.rst @@ -5,7 +5,7 @@ Model ``/model`` ``/model`` base endpoint provides a set of methods dedicated to data modeling. -Unlike other endpoints ``/model`` is basically a prefix to the actual endpoints that handle object types, property types, properties, relations and categories. You can see this endpoints collection as the **API Modeling** part of BEdita. +Unlike other endpoints ``/model`` is basically a prefix to the actual endpoints that handle object types, property types, properties, relations, categories, tags and project model information. You can see this endpoints collection as the **API Modeling** part of BEdita. Main operations available on these endpoints: @@ -16,6 +16,7 @@ Main operations available on these endpoints: * handle object type tags with ``/model/tags`` * define relations between objects with ``/model/relations`` * retrieve :term:`JSON SCHEMA` of object types and resources from ``/model/schema`` +* retrieve current project model data from ``/model/project`` .. toctree:: :caption: Model endpoints reference @@ -27,6 +28,7 @@ Main operations available on these endpoints: tags relations schema + project .. _api-model-naming: diff --git a/source/endpoints/model/object_types.rst b/source/endpoints/model/object_types.rst index ae0203a..b62d1f7 100644 --- a/source/endpoints/model/object_types.rst +++ b/source/endpoints/model/object_types.rst @@ -28,6 +28,7 @@ Creation of a new object type happens through ``POST /model/object_types`` endpo "name": "cats", "singular": "cat", "description": "This is a cat" + } } } @@ -191,18 +192,47 @@ Response 200 OK is expected. { "data": { - "id": 13, + "id": "13", "type": "object_types", "attributes": { - "username": "johndoe", - "name": "Johnny", - "surname": "Doe" + "name": "cats", + "singular": "cat", + "is_abstract": false, + "description": "This was a cat", + "associations": null, + "hidden": null, + "enabled": false, + "table": "BEdita/Core.Objects", + "parent_name": "objects" }, "meta": { - ... + "created": "2017-11-21T13:56:54+00:00", + "modified": "2017-11-21T13:56:54+00:00", + "core_type": false, + "alias": "Cats", + "relations": [] }, "relationships": { - ... + "left_relations": { + "data": [], + "links": { + "related": "http://api.example.com/model/object_types/13/left_relations", + "self": "http://api.example.com/model/object_types/13/relationships/left_relations" + } + }, + "right_relations": { + "data": [], + "links": { + "related": "http://api.example.com/model/object_types/13/right_relations", + "self": "http://api.example.com/model/object_types/13/relationships/right_relations" + } + }, + "parent": { + "links": { + "related": "http://api.example.com/model/object_types/13/parent", + "self": "http://api.example.com/model/object_types/13/relationships/parent" + } + } } }, "links": { diff --git a/source/endpoints/model/project.rst b/source/endpoints/model/project.rst new file mode 100644 index 0000000..74d35a2 --- /dev/null +++ b/source/endpoints/model/project.rst @@ -0,0 +1,23 @@ +Project model ``/model/project`` +================================ + +``/model/project`` endpoint returns a compact representation of the current project model. + +This endpoint is useful when you need a single resource describing model configuration at project level. + +Get project model +----------------- + +You can retrieve project model information by invoking ``GET /model/project``. + +.. http:get:: /model/project + +**Example request (get project model)**: + +.. sourcecode:: http + + GET /model/project HTTP/1.1 + Host: api.example.com + Accept: application/json + +Expected response is ``HTTP/1.1 200 OK`` with ``application/json`` body. diff --git a/source/endpoints/model/properties.rst b/source/endpoints/model/properties.rst index 8dcb450..dd807da 100644 --- a/source/endpoints/model/properties.rst +++ b/source/endpoints/model/properties.rst @@ -142,9 +142,9 @@ In this example we will simply disable the newly created property and change its .. sourcecode:: http PATCH /model/properties/1 HTTP/1.1 - Content-Type: application/json - + Host: api.example.com Accept: application/vnd.api+json + Content-Type: application/json { "data": { diff --git a/source/endpoints/trash.rst b/source/endpoints/trash.rst index 919d1b9..9bd2026 100644 --- a/source/endpoints/trash.rst +++ b/source/endpoints/trash.rst @@ -18,53 +18,47 @@ You can obtain trash contents by using ``GET /trash`` and ``GET /trash/(object_i ``GET /trash`` returns response ``200 OK`` and contents as array, in 'data', as described in following example. - **Example request**: +**Example request**: - .. sourcecode:: http +.. sourcecode:: http - GET /trash HTTP/1.1 - Host: example.com - Accept: application/json, text/javascript + GET /trash HTTP/1.1 + Host: example.com + Accept: application/json, text/javascript - **Example response**: +**Example response**: - .. sourcecode:: http +.. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: application/json + HTTP/1.1 200 OK + Content-Type: application/json - { - "data": [ - .... - ], - .... - } + { + "data": [] + } .. http:get:: /trash/(object_id) ``GET /trash/(object_id)`` returns response ``200 OK`` if content is found, ``404 Not Found`` otherwise. - **Example request**: +**Example request**: - .. sourcecode:: http +.. sourcecode:: http - GET /trash/154 HTTP/1.1 - Host: example.com - Accept: application/json, text/javascript + GET /trash/154 HTTP/1.1 + Host: example.com + Accept: application/json, text/javascript - **Example response**: +**Example response**: - .. sourcecode:: http +.. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: application/json + HTTP/1.1 200 OK + Content-Type: application/json - { - "data": { - .... - }, - .... - } + { + "data": {} + } Restore contents ----------------