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

Create a category

Creation of a new category happens through POST /model/categories endpoint.

POST /model/categories

Example request: create category:

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

GET /model/categories/{categoryId}

{categoryId} is the category identifier

Example request (get category):

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.

GET /model/categories/{categoryId}/object_categories

{categoryId} is the category identifier

Example request (get object categories):

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

Modify a category

You can modify a category by using PATCH /model/categories/{categoryId} endpoint.

PATCH /model/categories/{categoryId}

{categoryId} is the category identifier

Example request: disable category:

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:

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.

DELETE /model/categories/{categoryId}

{categoryId} is the category identifier

Example request: delete category:

DELETE /model/categories/1 HTTP/1.1
Host: api.example.com
Accept: application/vnd.api+json

Expected HTTP status response is 204 No Content.