Categories and tags documentation

.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'

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 <https://en.wikipedia.org/wiki/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``.

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
 

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 <https://en.wikipedia.org/wiki/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``.