# Filters in Region API
The Ability Platform features a filter parameter within the Principal Manager (aka Region API) that allows a user to filter queries from Principal Manager resources using Query Expression Language (QEL). This filter is optional, and if left empty, will apply no special filtering logic to a request.
When used, the QEL filter is added to the endpoint of the API query. Following is an example filter expression for Tenants:
"/tenants?filter="('abc' IN tags) AND (name = 'abc')"&limit=100"
# Covered APIs
The QEL filter applies to the following APIs:
- Application
- Connectivity Provider
- Contract
- Device
- Grant
- Group
- Identity Provider
- Operations
- Permissions
- Resources
- Roles
- Solution
- Tenant
- User
When applying a "filter" using QEL, note the following:
Parameter names and values in the expression are case sensitive.
If "filter" is available in the query, then the API will ignore all parameters except for "limit" and "filter".
If "filter" is available in the query, then in addition to "limit" and "filter", "scope" is a recognized parameter in the following APIs:
- Device
- Grant
- Permissions
- Resources
- Roles
- Solution
The QEL filter supports the parameters associated with each API, as described below.
# Application
The following parameters are supported by the QEL query filter:
- id
- name
- solutionId
- applicationType
- delegation
- tags
The applicationType is a finite list, consisting of:
- SinglePageApp
- Native
- Web
- Background
# Connectivity Provider
A Connectivity Provider provides connectivity for devices.
The following parameters are supported by the QEL query filter:
- name
- type
- identityType
# IdentityType
The identityType parameter (preceding) supports any of the following:
- device
- app
- user
# Contract
A contract is created between a tenant and a solution when a tenant signs up for the solution.
The following parameters are supported by the QEL query filter:
- solutionId
- tenantId
- name
- tags
# Device
Devices are managed by the Principal Manager and are also principal to access control.
The following parameters are supported by the QEL query filter:
- ipId
- id
- identity
- tenantId
- solutionId
- parentId
- connectivityProviderId
- tags
- grantId
# Grant
A grant is a combination of a role and (optionally) rules with conditions.
The following parameters are supported by the QEL query filter:
- name
- solutionId
- roleId
- tags
# Group
Groups offer the ability to simplify principal management. For example, users can be associated with a group and the group associated with a grant.
The following parameters are supported by the QEL query filter:
- id
- name
- tenantId
- tags
# Identity Provider
Identity providers offer user authentication as a service.
The following parameters are supported by the QEL query filter:
- name
- tags
- type
# Operations
An operation is a digital replica (metadata) of each API that is publicly available in the Ability Platform. The Info Model API returns only the operations lists that are available based on the query filter parameter.
The following parameters are supported by the QEL query filter:
- solutionId
- operationId
- permission
- tags
# Permissions
Permissions are used to restrict access to specific resources in the Ability
Platform. For example, an "app_read" permission should be available to the
principal who needs access to the /GET/apps API.
The following parameters are supported by the QEL query filter:
- solutionId
- name
- tags
# Resources
Resources denote the entities in the Ability Platform that require protection.
The following parameters are supported by the QEL query filter:
- solutionId
- type
- tags
# Roles
A role is a named collection of permissions.
The following parameters are supported by the QEL query filter:
- solutionId
- name
- permission
- tags
# Solution
A solution is a container for applications, grants, etc.
The following parameters are supported by the QEL query filter:
- name
- tags
- scope
- namespace
# Tenant
A tenant is an organization or entity that signs up for an Ability Solution.
The following parameters are supported by the QEL query filter:
- name
- tags
# User
A user is an actor that accesses the Ability Platform.
The following parameters are supported by the QEL query filter:
- tenantId
- ipId
- identity
- tags
# API Response Codes
| Code | Description |
|---|---|
| 201 | Created |
| 200 | Request execution is successful |
| 400 | Request improperly formatted |
| 401 | Request lacks authorization header |
| 403 | Principal doesn't have permission to access the requested resource |
| 404 | Resource is not found. Also, from a security standpoint, if the request is /GET and the principal doesn't have authorization |