API reference
Airflows provides a powerful and flexible GraphQL API, synchronized with the data model.
It allows to build data-intensive applications on top of it.
It enables easy integration with other platforms, generation of new opportunities, greater agility in transformation processes, job automation, and more.
An API console is available in https://<your-instance-fqdn>/graphql.
API can be tested using this console before integrating into custom applications.
There is a button "copy curl" that exports the GraphQL query to an HTTP POST curl request in order to easy the portability to other platforms.
Login
Login into the API with a valid username and password in order to obtain a valid access token.
Then, use the access token in every API call to identify the user.
Current user
Obtain current user by passing a valid access token.
Querying data
All the information stored in Airflows can be queried using the API. This includes model information also (i.e. "Models" schema).
Query parameters
Queries can be customized using several parameters:
| Parameter name | Description | Example |
|---|---|---|
| limit | Number of entities to query (i.e. to enable query pagination). | limit: 10 |
| offset | Number of entities to skip (i.e. to enable query pagination). | offset: 100 |
| orderBy | Order criteria. | orderBy: [{attribute: name direction: ASC nullsGo: FIRST}] |
| where | Filter criteria. | where: {id: {EQ: 10}} |
Note that the results can be renamed specifying a label before the entity or field names.
Query criteria
Compose a filter criteria combining different operators.
Depending on field type, several operators are available:
| Operator | Description |
|---|---|
| EQ | True if the field is equals to the parameter. |
| GE | True if the field is greater than or equals to the parameter. |
| GT | True if the field is greater than the parameter. |
| ILIKE | True if the field matches case insensitive the pattern (i.e. name ILIKE '%peter%'). |
| IN | True if the field is included in a set of values. |
| IS_NULL | True if the field is NULL. |
| LE | True if the field is less than or equals to the parameter. |
| LIKE | True if the field matches the pattern (i.e. name ILIKE '%Peter%'). |
| LT | True if the field is less than the parameter. |
| NE | True if the field is not equals to the parameter. |
| SEARCH | True if the field matches the free text search filter. |
The following boolean operators are supported:
| Operator | Description |
|---|---|
| OR | Must match any of the combined conditions (disjunction). |
| AND | Must match all of the combined conditions (conjunction). |
| NOT | Negates a filter. |
Use the following operators to specify a more specific search request in the free-text search criteria:
| Operator | Description | Example value |
|---|---|---|
| :* | Search any term starting with a prefix | lad:* |
| | | OR condition. Search results containing some of the terms. | ladies |
| & | AND condition. Search results containing all of the terms. | men & shirts |
| () | Group parts of the expression to give more precedence. | (men |
Querying related information
Related entities can be queried by joining them into the main query in both directions (i.e. from referencing to referenced entity [n-to-1] and opposite [1-to-n]).
When querying related entities (1-to-n), additional parameters can be specified:
| Parameter name | Description | Example |
|---|---|---|
| joinType | Joint type (i.e. INNER [only entities with related entities], OUTER [all the entities]) | joinType: INNER |
| offset | Number of entities to skip (i.e. to enable query pagination). | offset: 100 |
| orderBy | Order criteria. | orderBy: [{attribute: name direction: ASC nullsGo: FIRST}] |
| where | Filter criteria. | where: {id: {EQ: 10}} |
Example query: Get all the categories that have products, and for each category, get the first three products ordered by name.
Querying documents
Fields of type document have special attributes which can be queried independently.
Example query: Get image data including thumbnail for product which id is 98.
In order to store the document, there are additional endpoints:
| Operation | Endpoint | Example |
|---|---|---|
| Get document | GET /wopi/files/:schemaName/:entityName/:id/:attributeName/contents | GET /wopi/files/Demo/Product/99/largeImage/contents?inline=true&access_token=eyJh... (i.e. "if inline is not specified then attachment will be used") |
| Post document | POST /document/:schemaName/:entityName/:id/:attributeName/contents | POST /document/Demo/Product/99/largeImage/contents |
Variables
Parameter values can be also specified as variables.
Editing data
GraphQL API offers mutations also in order to alter the stored data in the platform.
Creating new data
Add data using "create" operations.
Updating data
Update data using "update" operations.
Deleting data
Delete data using "delete" operations.
Aggregations
GraphQL API offers aggretations in order to analyze data.
Depending on the field type, different aggregation operations are available:
| Operation | Description |
|---|---|
| _avg | The average value. |
| _max | The maximum value. |
| _min | The minimum value. |
| _sum | The sum of the values. |
| _count | The count of the values. |
| _distinct_count | The count of the distinct values. |
| _stddev | The standard deviation of the values. |
| _variance | The variance of the values. |
Buckets
GraphQL API offers buckets in order to group information based on different criteria.
Then, information on each bucket can be aggregated.
Buckets can be specified in two different ways:
Custom bounds buckets
Example: Count products in the following price ranges:
- Bucket 0: Products which price is less than 10.
- Bucket 1: Products which price is greater than or equals to 10 and less than 50.
- Bucket 2: Products which price is greater than or equals to 50 and less than 100.
- Bucket 3: Products which price is greater than or equals to 100.
Equal-width buckets
Example: Count products in ten different groups of prices that go from 0 to 100.
Other functions
Refreshing the access token
Access token expires each 60 minutes. Refresh token using refreshToken operation.
