CaaS Platform

Requests with API Key must include an HTTP header with a bearer token: Authorization: Bearer <key>.
The value of key should be the value of the key attribute of the API Key used.

For more information, see Validation of API Keys.

It is possible to generate a short-lived (up to 24 hours) security token for an API Key. The token includes the same permissions as the API Key it was generated for.

There are two ways to generate and use these tokens:

If multiple authentication mechanisms are used in a request, only the first one found is evaluated. The precedence is as follows:

1. The query parameter securetoken
2. The Authorization header
3. The cookie securetoken

Authorization of an API Key is performed based on each permission that is part of the key. The list of permissions is defined in the permissions attribute of the key.

A permission has the following attributes:

When checking a permission, the url attribute is used. Its value is compared to the URL path of an incoming request. The type of check depends on the permissionMode of the permission.

There are three different permission modes:

Difference between local and global API Keys

The following table illustrates the difference in authorization between local and global API Keys when using the permission modes PREFIX or REGEX.

The following endpoints are available for managing API Keys:

The database to use depends on the type of API Key, see chapter API Keys.

Example for creating a local API Key using curl:

The API Key shown in this example is of type "local" because it is defined in the apikeys collection under the database <tenant> and is therefore local to that database. The permission applies to all paths starting with /<tenant>/<collection>, since the permission mode PREFIX is used, and includes all HTTP methods listed in methods.

Every API Key is validated against a stored JSON schema when created and updated. The JSON schema ensures the basic structure of API Keys and can be queried at /<database>/_schemas/apikeys.

Further validations ensure that no two API Keys with the same key can be created. Also, an API Key may not contain a URL more than once.

If an API Key does not meet the requirements, the corresponding request is rejected with HTTP status 400.

If the JSON schema was not successfully stored in the database beforehand, requests are answered with HTTP status 500.

Filters are used whenever documents should be retrieved based on their content rather than their ID. This allows both individual and multiple documents to be retrieved.

For example, the query for all English-language documents from the products collection has the following structure:

https://REST-HOST:PORT/<database>/products?filter={fs_language:"EN"}

By default, the interface returns all JSON data in HAL format. Thus, they are not just raw data, as is traditionally the case with unstructured JSON content.

The HAL format offers the advantage of simple yet powerful structuring. In addition to the required content, the results contain additional meta-information about the structure of this content.

Example

In this example, a filtered query was executed. Without knowing the exact content, its structure can be read directly from the meta-information. The REST Interface returns three results matching the filter criteria from a set of five documents and presents them on a single page.

The results of the REST Interface are always paginated to avoid performance issues with large collections. To control the requested page and the number of documents per page, the HTTP query parameters page and pagesize can be used in GET requests.
The default value for the pagesize parameter is set to 20 in the CaaS platform, and the maximum is 100.
These values can be changed for on-premises installations (see Operations Guide).

More information can be found in the RESTHeart documentation.

CaaS documents can reference other CaaS documents. When processing documents, the referenced content is often needed directly. To avoid sequential queries in these cases, the query parameter resolveRef can be used.

The following two JSON documents illustrate this:

In the first document, the JSON under formData.ps_audio.value.url contains an absolute URL to another document in the CaaS. The following request shows how this reference is resolved in the same request that reads the document.

The value of the query parameter must be the URL path specified in the JSON. The response then contains an additional attribute _resolvedRefs:

The resolveRef parameter is also supported for collection queries. In this case, references in all returned documents are resolved. The documents of the resolved references are collected in a new, additional document, which is then added to the response array.

The runtime of queries with filters (see chapter Use of Filters) can increase as the number of documents in a collection grows. If it exceeds a certain value, the query will be answered by the REST Interface with HTTP status 408. More efficient execution can be achieved by creating an index on the attributes used in the relevant filter queries.

Detailed information about database indexes can be found in the documentation of MongoDB.

The exact definitions can be retrieved at https:/REST-HOST:PORT/<database>/<collection>/_indexes/.

To create or update a GraphQL application, send a PUT request with the app definition to the following URL:
https://REST-HOST:PORT/<tenant>/gql-apps/<app-uri>

Notes:

This provisions an endpoint at https://REST-HOST:PORT/graphql/<app-uri>, which can then be used for GraphQL queries. Information about executing GraphQL queries can be found in chapter GraphQL API.

All operations on GraphQL applications are automatically mirrored in the /caas_admin/gql-apps collection for technical reasons. See chapter Resynchronizing existing GraphQL applications for information on how this mechanism can also be triggered manually if needed.

Providing the App Definition
There are two ways to provide the app definition in the PUT request:

Notes

To delete a GraphQL application, a DELETE request is sent to the following URL:
https://REST-HOST:PORT/<tenant>/gql-apps/<tenant>___<name>

Under certain conditions, such as after restoring individual collections from a backup, it may happen that previously created GraphQL applications are no longer synchronized. In such cases, all tenant-specific GraphQL applications must be resynchronized.

To resynchronize all existing GraphQL applications of all tenants, a POST request must be made to the HTTP endpoint /_logic/sync-gql-apps.

The GraphQL API can be queried via the following HTTP endpoints:

https://REST-HOST:PORT/graphql/<app-uri>

To query data, send a POST request to the desired endpoint and specify the query with JSON in the request body, e.g.:

We offer an experimental MCP server that helps AI agents interact better with the FirstSpirit GraphQL API. It helps AI create valid GraphQL queries and check their functionality. For more information, see the CaaS MCP Server documentation and the FirstSpirit GraphQL API documentation.

This chapter describes a use case for a GraphQL application as an example. For this we will outline the individual steps that belong to the creation of a GraphQL application and its later use.

Create the GraphQL app definition

In the example scenario, a GraphQL application is created that can be used to query data records located in the CaaS. The data sets used here are the products from the example project of the fictitious company “Smart Living”. Image references and product categories in the data sets are resolved directly.

The entire command to create the GraphQL app definition for this example scenario looks like this.

Schema of the GraphQL app definition

The schema used for the example contains the following definitions.

Lines 1, 9 and 14 of the schema are the starting point for the type definitions of the objects used in the GraphQL app. In addition, each GraphQL schema contains a query type (line 22) that defines what data can be queried by a GraphQL app. More details about schemas in GraphQL can be found in the GraphQL documentation.

In line 23 we define a query with the name products, which returns a collection of [Product]. To specify the languages in which we need this data, we add the _language variable. As most of our customers are German or English, we also add a default value of ["DE", "EN"]. This marks the variable as optional.

Mapping the GraphQL app definition

The GraphQL app definition mapping represents the connection between the schema and the data in the database. Each type described in the schema generally requires an explicit entry, so this part of a GraphQL app definition is usually the longest. There may be situations where the fields in the type should be named exactly as the keys of the data. In this special case, no explicit entry in the mapping is necessary. For details about the mapping in GraphQL app definition, see the corresponding chapter in RESTHeart documentation.
The following example is an excerpt from creating a GraphQL app definition and clarifies some use cases.

The first use case considered is the so-called field to field mapping. In this type of mapping, a field in the type is assigned a corresponding attribute of the data. An example of this can be seen in line 3, where the field Category.name from the schema refers to attribute displayName from the data.

The second use case is the field to query mapping. Here a field in the type is mapped to the result of a data query. An example of such a mapping can be found in line 45ff: the field Query.products is mapped by the data found in the REST Interface under /mycorp-dev/d8db6f24-0bf8-4f48-be47-5e41d8d427fd.preview.content and correspond to the filters entityType": "product" and "locale.identifier": { "$in": { "$arg":"_language" } }. This means that exactly those products are queried which are located in the defined source, represent an entity of “product” and use one of the language abbreviations passed in the “_language” argument.

Another example of a “field to query mapping” can be found starting at line 29. In this mapping definition, the product categories, which are maintained in separate records, are identified using a foreign key relationship. The complete entry from line 29-42 states that the product.categories field will list all product categories that are under /mycorp-dev/d8db6f24-0bf8-4f48-be47-5e41d8d427fd.preview.content, whose identifier is stored in the formData.tt_categories.value.identifier field, and whose locale.identifier exactly matches what is in the product record as locale.identifier. Since a product can reference multiple categories in the dataset under formData.tt_categories.value.identifier, the key $in is used here.

Using the GraphQL app

Requests can now be made to a GraphQL application using this app definition.

This request example shows how to call the GraphQL app using curl. The app is always available at /graphql/<descriptor.uri>. Through this query, product data is retrieved depending on the variable $lang. The variable is passed as a value to the _language argument defined in the schema. Since a default value for _language is included in the schema, specifying a value is optional in this scenario. Further details on query arguments and variables can be found in the GraphQL documentation.

Aggregations can be used to create complex queries to the CaaS. For example, it’s possible to dynamically add a computed attribute to the returned documents. Much more complex aggregations can be created. A full list of possible aggregation stages and operators can be found here.

This tutorial serves as an introduction to creating and using GraphQL apps. To complete it you need to be familiar with the REST Interface in terms of authentication and querying documents.

GraphQL apps allow you to query your CaaS documents via your own GraphQL API endpoints. These endpoints also make the document data accessible in a specific format/schema that you define.

In the following steps we will be creating such a GraphQL app and use it to query document data. We’ll be using curl to send HTTP requests, but you can use other alternative tools.