Last updated Jun 6, 2023

Rate this page:

Filtering and Paginating the Workspaces API

Overview

Workspaces API uses a cursor-based pagination model. In this model, initial requests contain a body with parameters for filtration. Initial requests that yield results with more than one page of data will contain cursors in the response body for navigating backward and forward to get new portions of data. This brings us to two different request types:

  • Initial request with filtration properties in the body
  • Cursor only request containing the cursor from previous response

Both request types should not overlap. Attempting to use a cursor in an initial workspaces request will lead to the 400 code in the response. The same is true when attempting to use any of the other request parameters besides cursor when requesting a second page of data.

Filtering the Workspaces API

Workspaces API provides mechanisms for filtration that can be managed by using limit, sort, and/or query parameters.

1
2
{
  "limit": 20,
  "sort": [
    {
      "field": "attributes.type",
      "order": "asc"
    }
  ],
  "query": {
    "and": [
      {
        "field": {
          "name": "attributes.type",
          "values": [
            "confluence"
          ]
        }
      },
      {
        "searchWorkspaces": "some-particular-workspace"
      }
    ]
  }
}

Using query for filtration

Workspaces API provides the ability to filter search results by using simple query format. In order to filter results by field, use the field term. List of queryable fields can be below:

  • attributes.owner
  • attributes.type
  • relationships.entitlement.attributes.plan
  • attributes.name.raw
  • attributes.sandbox.type
  • relationships.bundle.attributes.type
  • id
1
2
{
  "query": {
    "field": {
      "name": "attributes.type",
      "values": [
        "confluence"
      ]
    }
  }
}

Workspaces API also allow us to search for particular workspace by using a searchWorkspaces term.

1
2
{
  "query": {
    "searchWorkspaces": "some-particular-workspace"
  }
}

Terms can be combined by using AND operation.

1
2
{
  "query": {
    "and": [
      {
        "field": {
          "name": "attributes.type",
          "values": [
            "confluence"
          ]
        }
      },
      {
        "field": {
          "name": "relationships.entitlement.attributes.plan",
          "values": [
            "Enterprise"
          ]
        }
      }
    ]
  }
}

Terms can also be combined by using NOR operation.

1
2
{
  "query": {
    "nor": [
      {
        "field": {
          "name": "attributes.type",
          "values": [
            "confluence"
          ]
        }
      },
      {
        "field": {
          "name": "attributes.type",
          "values": [
            "jira-software"
          ]
        }
      }
    ]
  }
}
Bulk Workspace hydration

Based on the input id (workspace ids), returns workspaces data present for ids. Number of values of id in a query can't be greater than 1000

1
2
{
  "limit": 5,
  "query": {
    "and": [
      {
        "field": {
          "name": "id",
          "values": [
            "ari:cloud:confluence::site/{siteId1}",
            "ari:cloud:confluence::site/{siteId2}"
          ]
        }
      }
    ]
  }
}

Note: If the values array size (of field id) is greater than the limit, than limit number of workspaces will be returned with cursor. To fetch the remaining workspaces, client has to use the cursor.

Features field:

New field features is added to query. It takes an array of features and return all the workspaces that has any one of the feature. Currently, we only support one value in the feature.

1
2
{
  "query": {
    "and": [
      {
        "features": ["relationships.feature.allowlisting"]
      }
    ]
  }
}

Policies Filter:

New field policies is added to query. It takes an array of policies and return all the workspaces that has any one of the policy. Currently, admin-portfolio only supports one value in the feature.

1
2
{
  "query": {
    "and": [
      {
        "policies": ["relationships.policy.customDomains.availableTargets"]
      }
    ]
  }
}

Limiting the number of items per page

It is possible to limit number of results that will be returned per page using limit property.

1
2
{
  "limit": 20
}

The limit property specifies maximum page size for search results. If limit is not present in the search request it will use 20 as a default page size. It can accept values from 1 to 1000.

Sorting search results

Worspaces API allow us to sort search results by one or several fields. List of sortable fields could be found below:

  • attributes.owner
  • attributes.type
  • relationships.entitlement.attributes.plan
  • attributes.name.raw
  • links.self
1
2
{
  "sort": [
    {
      "field": "attributes.type",
      "order": "asc"
    }
  ]
}

The sort order provided must be either "asc" or "desc".

Search without filtration

It is also possible to search workspaces without filtering. If no json body is added to the request or if the request contains an empty object, an unfiltered list of workspaces will be returned.

1
2
{}

Paginating the Workspaces API

After the initial request, we will get response that contains the first page of workspace data and also cursors that are linked to the next and previous pages (if applicable). We can use these cursors to request next or previous pages by using a cursor only request. This type of request will contain only a cursor in the request body. This type of request is not compatible with the properties that were described previously. Cursor request that contains any property but the cursor in the request body will return error code 400 in the response.

1
2
{
  "cursor": "c29tZS1iYXNlLTY0LWVuY29kZWQtY3Vyc29y"
}

Value for cursor here is what we get in previous request in links section. In the response for this request will be the cursor to the next page (if applicable) that can be used to continue pagination.

Rate this page: