Skip to content

Category tree api

Jump to bottom Edit New page
Kristoffer Hägelstam edited this page Jul 2, 2020 · 16 revisions

Category trees main purpose is to represent a shared tree structure that can be used as filters for other resources, one example of this could be Order hardware where the category tree is used to filter available hardware into different categories.

It's important that the category tree is shared and simply referenced within the resource so that multiple resources can use the same category tree, such as an administration view and the end user view.

Category trees uses the standard and custom data concept.

Category tree object

The category tree is represented as the following model.

{
    "id": "",
    "name": "",
    "nameTranslations": {},
    "description": "",
    "descriptionTranslations": {},
    "authQuery": "",
    "categories": category-tree-object[]
}

Note that it contains a recursive list (categories) of its self

List category trees

Loads available category trees, will include both standard and custom category trees if not specified otherwise.

Http request

GET /api/categorytree

Permissions

Scope Description
None Allows loading all category trees, all auth queries will be evaluated
Platform.CategoryTree Allows skipping evaluating auth queries via query parameter

Optional query parameters

Name Description
excludeStandard Excludes data from standard platform and active modules
excludeCustom Excludes custom data stored in database
skipAuthQueries Skip evaluating auth queries on category trees if scope Platform.CategoryTree is present
search Only includes category trees where name contains the value
skip Number of items to be skipped
take Number of items to be included

Request headers

Header Value
Authorization Bearer {token}

Response
If successful, returns list of category tree objects with a status code 200 Ok.
If skipAuthQueries is set but required scope is missing, returns missing-scope with status code 400 BadRequest.

Response Body

[
    {
        "id": "",
        "name": "",
        "nameTranslations": {},
        "description": "",
        "descriptionTranslations": {},
        "authQuery": "",
        "categories": category-tree-object[]
    }
]

Examples

  1. Load all available category trees where the name contains with ABC

    GET https://ateazephyr.com/api/categorytree?search=ABC

  2. Only load custom category trees stored in database

    GET https://ateazephyr.com/api/categorytree?excludeStandard

  3. Skips evaluating auth queries

    GET https://ateazephyr.com/api/categorytree?skipAuthQueries

Load specific category tree

Loads category tree with specified id, will use both standard and custom category trees if not specified otherwise.

Http request

GET /api/categorytree/{id}

Permissions

Scope Description
None Allows loading category tree, auth query will be evaluated
Platform.CategoryTree Allows skipping evaluating auth query via query parameter

Optional query parameters

Name Description
excludeStandard Excludes data from standard platform and active modules
excludeCustom Excludes custom data stored in database
skipAuthQuery Skip evaluating auth query on category tree

Request headers

Header Value
Authorization Bearer {token}

Response
If successful, returns category tree object with a status code 200 Ok.
If no category tree is found, returns status code 404 NotFound.
If found but auth query failed to evaluate, returns status code 403 Forbidden.
If skipAuthQuery is set but required scope is missing, returns missing-scope with status code 400 BadRequest.

Response body

{
    "id": "",
    "name": "",
    "nameTranslations": {},
    "description": "",
    "descriptionTranslations": {},
    "authQuery": "",
    "categories": category-tree-object[]
}

Examples

  1. Load category tree

    GET https://ateazephyr.com/api/categorytree/00000000-0000-0000-0000-000000000000

  2. Load category tree but skip evaluating auth query

    GET https://ateazephyr.com/api/categorytree/00000000-0000-0000-0000-000000000000?skipAuthQuery

Update category tree

Updates specified category tree with partial changes.

  • Loads the category tree
  • Applies the partial changes
  • Saves as custom category tree

Http request

PUT /api/categorytree/{id}

Required permissions

Platform.CategoryTree

Request headers

Header Value
Authorization Bearer {token}
Content-Type application/json

Request body
Only include the properties that you want to change, should be a json object.

Property Description
name Changes the default name used when no translation is available
nameTranslations Changes the available translations
description Changes the default description used when no translation is available
descriptionTranslations Changes the available translations
authQuery Changes auth query used to evaluate if user should have access to resource
addedCategories Add new child categories
removedCategories Removes the child categories with matching id:s
changedCategories Changes the child categories with matching id:s
reorderCategories Changes the order of the child categories by specifing a list of category id:s that represent the new order

Response
If successful, returns status code 200 Ok.
If no category tree is found, returns status code 404 NotFound.
If no changes are sent in request body, returns no-changes with status code 400 BadRequest.

Examples

  1. Change name, description, swedish translations and authQuery

    PUT https://ateazephyr.com/api/categorytree/00000000-0000-0000-0000-000000000000
{
    "name": "New name!",
    "nameTranslations": {
        "sv": "Nytt namn!"
    },
    "description": "New description!",
    "descriptionTranslations": {
        "sv": "Ny beskrivning!"
    },
    "authQuery": "User.Roles.Contains(\"Santa\")"
}

  2. Add and remove child categories

    PUT https://ateazephyr.com/api/categorytree/00000000-0000-0000-0000-000000000000
{
    "addedCategories": [
        {
             "name": "...",
             "nameTranslations": {
                 "sv": "...",
                 "no": "...",
                 "fi": "..."
             },
             "description": "...",
             "descriptionTranslations": {
                 "sv": "...",
                 "no": "...",
                 "fi": "..."
             },
             "authQuery": "...",
             "categories": category-tree-object[]
         }
    ],
    "removedCategories": [
        "category-id"
    ]
}

  3. Change existing child category with new name, supported properties are the same as request body as well as id-property

    PUT https://ateazephyr.com/api/categorytree/00000000-0000-0000-0000-000000000000
{
    "changedCategories": [
        {
            "id": "category-id",
            "name": "Wooo new name!"
        }
    ]
}

  4. Change order of child categories, ex: category tree child order category-id-1,category-id-2,category-id-3 will become category-id-3,category-id-1,category-id-2

    PUT https://ateazephyr.com/api/categorytree/00000000-0000-0000-0000-000000000000
{
    "reorderCategories": [
        "category-id-3",
        "category-id-1",
        "category-id-2"
    ]
}

  5. Change order of sub child categories

    PUT https://ateazephyr.com/api/categorytree/00000000-0000-0000-0000-000000000000
{
    "changedCategories": [
        {
            "id": "category-id",
            "reorderCategories": [
                 "sub-category-id-2",
                 "sub-category-id-3",
                 "sub-category-id-1"
             ]
        }
    ]
}

Create new category tree

Creates a new custom category tree.

Http request

POST /api/categorytree

Required permissions

Platform.CategoryTree

Request headers

Header Value
Authorization Bearer {token}
Content-Type application/json

Request body
Body should be a json object.

Property Description
name Default name used when no translation is available
nameTranslations Available translations, ex: {"locale":"value"} optional
description Default description used when no translation is available optional
descriptionTranslations Available translations, ex: {"locale":"value"} optional
authQuery Auth query used to evaluate if user should have access to resource optional
categories Category tree children

Response
If successful, returns status code 200 Ok.
If missing name, returns missing-name with status code 400 BadRequest.
If missing categories, returns missing-categories with status code 400 BadRequest.

Examples

POST https://ateazephyr.com/api/categorytree
{
    "name": "...",
    "nameTranslations": {
        "sv": "...",
        "no": "...",
        "fi": "..."
    },
    "description": "...",
    "descriptionTranslations": {
        "sv": "...",
        "no": "...",
        "fi": "..."
    },
    "authQuery": "...",
    "categories": category-tree-object[]
}

Delete category tree

Deletes a custom category tree.

Http request

DELETE /api/categorytree/{id}

Required permissions

Platform.CategoryTree

Request headers

Header Value
Authorization Bearer {token}

Response
If successful, returns status code 200 Ok.
If no category tree is found, returns status code 404 NotFound.

Examples

DELETE https://ateazephyr.com/api/categorytree/00000000-0000-0000-0000-000000000000
Add a custom footer
Clone this wiki locally