diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index 00d7c32..b0a2c66 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -10,7 +10,7 @@ on: jobs: docs: - runs-on: 'ubuntu-20.04' + runs-on: 'ubuntu-latest' steps: - name: 'Checkout current revision' diff --git a/source/endpoints/model/categories.rst b/source/endpoints/model/categories.rst new file mode 100644 index 0000000..289474d --- /dev/null +++ b/source/endpoints/model/categories.rst @@ -0,0 +1,187 @@ +Categories ``/model/categories`` +================================ + +``/model/categories`` endpoint manages categories for object types. + +Categories are associated to object types and can be used to classify objects and filter resources, for instance through ``filter[categories]`` on object endpoints. + +With this endpoint you can: + +* create, update and remove categories +* get a single category +* list categories +* retrieve object categories linked to a category + +.. _api-model-categories: + +Create a category +----------------- + +Creation of a new category happens through ``POST /model/categories`` endpoint. + +.. http:post:: /model/categories + +**Example request: create category**: + +.. sourcecode:: http + + POST /model/categories HTTP/1.1 + Host: api.example.com + Accept: application/vnd.api+json + Content-Type: application/json + + { + "data": { + "type": "categories", + "attributes": { + "name": "new-name", + "label": "New Label", + "object_type_name": "events" + } + } + } + +Main attributes used on category creation are: + +* ``name`` category name in lowered `snake_case `_ format +* ``label`` display label +* ``object_type_name`` object type associated with this category + +Expected response is ``HTTP/1.1 201 Created``, with ``application/vnd.api+json`` body data representing category just created. + +If category already exists or input data is not valid, POST fails and response will be ``400 Bad Request - Invalid data``. + +Get a single category +--------------------- + +You can obtain a single category by invoking ``GET /model/categories/{categoryId}``. + +.. http:get:: /model/categories/{categoryId} + +* ``{categoryId}`` is the category identifier + +**Example request (get category)**: + +.. sourcecode:: http + + GET /model/categories/1 HTTP/1.1 + Host: api.example.com + Accept: application/vnd.api+json + +Expected response is ``HTTP/1.1 200 OK``. + +If category is not found, response will be ``404 Not Found``. + +Get object categories +--------------------- + +To retrieve object categories linked to a category invoke ``GET /model/categories/{categoryId}/object_categories``. + +.. http:get:: /model/categories/{categoryId}/object_categories + +* ``{categoryId}`` is the category identifier + +**Example request (get object categories)**: + +.. sourcecode:: http + + GET /model/categories/1/object_categories HTTP/1.1 + Host: api.example.com + Accept: application/vnd.api+json + +Expected response is ``HTTP/1.1 200 OK`` with a list in ``"data"``. + +Categories list +--------------- + +To retrieve a list of categories you can invoke ``GET /model/categories`` and use common filters like :ref:`filter-field` or :ref:`filter-search`. + +.. http:get:: /model/categories + +**Example request: get categories**: + +.. sourcecode:: http + + GET /model/categories HTTP/1.1 + Accept: application/vnd.api+json + +Response will contain an array of ``categories`` in typical list format as shown in :ref:`api-responses`. + +You can filter by object type using ``filter[type]``. + +**Example request: get categories by type**: + +.. sourcecode:: http + + GET /model/categories?filter[type]=events HTTP/1.1 + Accept: application/vnd.api+json + +Modify a category +----------------- + +You can modify a category by using ``PATCH /model/categories/{categoryId}`` endpoint. + +.. http:patch:: /model/categories/{categoryId} + +* ``{categoryId}`` is the category identifier + +**Example request: disable category**: + +.. sourcecode:: http + + PATCH /model/categories/1 HTTP/1.1 + Host: api.example.com + Accept: application/vnd.api+json + Content-Type: application/json + + { + "data": { + "id": "1", + "type": "categories", + "attributes": { + "enabled": false + } + } + } + +**Example request: change label**: + +.. sourcecode:: http + + PATCH /model/categories/1 HTTP/1.1 + Host: api.example.com + Accept: application/vnd.api+json + Content-Type: application/json + + { + "data": { + "id": "1", + "type": "categories", + "attributes": { + "label": "nice category!" + } + } + } + +Expected response is ``HTTP/1.1 200 OK``. + +Remove a category +----------------- + +You can delete a category permanently by using ``DELETE /model/categories/{categoryId}`` endpoint. + +.. http:delete:: /model/categories/{categoryId} + +* ``{categoryId}`` is the category identifier + +**Example request: delete category**: + +.. sourcecode:: http + + DELETE /model/categories/1 HTTP/1.1 + Host: api.example.com + Accept: application/vnd.api+json + +Expected HTTP status response is ``204 No Content``. + +If category is not found, response will be ``404 Not Found``. diff --git a/source/endpoints/model/index.rst b/source/endpoints/model/index.rst index ffda439..5943ddd 100644 --- a/source/endpoints/model/index.rst +++ b/source/endpoints/model/index.rst @@ -5,22 +5,26 @@ 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 and relations. 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 and categories. You can see this endpoints collection as the **API Modeling** part of BEdita. Main operations available on these endpoints: * list, create, update and (de)activate object types via ``/model/object_types`` * define new property types using :term:`JSON SCHEMA` ``/model/property_types`` +* handle object type categories with ``/model/categories`` * handle object type properties with ``/model/properties`` +* 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`` .. toctree:: :caption: Model endpoints reference + categories object_types property_types properties + tags relations schema diff --git a/source/endpoints/model/tags.rst b/source/endpoints/model/tags.rst new file mode 100644 index 0000000..9d4bf88 --- /dev/null +++ b/source/endpoints/model/tags.rst @@ -0,0 +1,155 @@ +Tags ``/model/tags`` +==================== + +``/model/tags`` endpoint manages tags for object types. + +Tags are associated to object types and can be used to classify objects and filter resources, for instance through ``filter[tags]`` on object endpoints. + +With this endpoint you can: + +* create, update and remove tags +* get a single tag +* list tags +* retrieve object tags linked to a tag + +Create a tag +------------ + +Creation of a new tag happens through ``POST /model/tags`` endpoint. + +.. http:post:: /model/tags + +**Example request: create tag**: + +.. sourcecode:: http + + POST /model/tags HTTP/1.1 + Host: api.example.com + Accept: application/vnd.api+json + Content-Type: application/json + + { + "data": { + "type": "tags", + "attributes": { + "name": "test-tag", + "label": "Test Tag" + } + } + } + +Main attributes used on tag creation are: + +* ``name`` tag name in lowered `snake_case `_ format +* ``label`` display label + +Expected response is ``HTTP/1.1 201 Created``, with ``application/vnd.api+json`` body data representing tag just created. + +If tag already exists or input data is not valid, POST fails and response will be ``400 Bad Request - Invalid data``. + +Get a single tag +---------------- + +You can obtain a single tag by invoking ``GET /model/tags/{tagId}``. + +.. http:get:: /model/tags/{tagId} + +* ``{tagId}`` is the tag identifier + +**Example request (get tag)**: + +.. sourcecode:: http + + GET /model/tags/1 HTTP/1.1 + Host: api.example.com + Accept: application/vnd.api+json + +Expected response is ``HTTP/1.1 200 OK``. + +If tag is not found, response will be ``404 Not Found``. + +Get object tags +--------------- + +To retrieve object tags linked to a tag invoke ``GET /model/tags/{tagId}/object_tags``. + +.. http:get:: /model/tags/{tagId}/object_tags + +* ``{tagId}`` is the tag identifier + +**Example request (get object tags)**: + +.. sourcecode:: http + + GET /model/tags/1/object_tags HTTP/1.1 + Host: api.example.com + Accept: application/vnd.api+json + +Expected response is ``HTTP/1.1 200 OK`` with a list in ``"data"``. + +Tags list +--------- + +To retrieve a list of tags you can invoke ``GET /model/tags`` and use common filters like :ref:`filter-field` or :ref:`filter-search`. + +.. http:get:: /model/tags + +**Example request: get tags**: + +.. sourcecode:: http + + GET /model/tags HTTP/1.1 + Accept: application/vnd.api+json + +Response will contain an array of ``tags`` in typical list format as shown in :ref:`api-responses`. + +Modify a tag +------------ + +You can modify a tag by using ``PATCH /model/tags/{tagId}`` endpoint. + +.. http:patch:: /model/tags/{tagId} + +* ``{tagId}`` is the tag identifier + +**Example request: modify tag**: + +.. sourcecode:: http + + PATCH /model/tags/1 HTTP/1.1 + Host: api.example.com + Accept: application/vnd.api+json + Content-Type: application/json + + { + "data": { + "id": "1", + "type": "tags", + "attributes": { + "label": "Nice tag" + } + } + } + +Expected response is ``HTTP/1.1 200 OK``. + +Remove a tag +------------ + +You can delete a tag permanently by using ``DELETE /model/tags/{tagId}`` endpoint. + +.. http:delete:: /model/tags/{tagId} + +* ``{tagId}`` is the tag identifier + +**Example request: delete tag**: + +.. sourcecode:: http + + DELETE /model/tags/1 HTTP/1.1 + Host: api.example.com + Accept: application/vnd.api+json + +Expected HTTP status response is ``204 No Content``. + +If tag is not found, response will be ``404 Not Found``.