Pages

Do not make Graniitti API requests in client-side code that is accessible to parties you do not trust, as this will expose your token to them. Use the Graniitti API only in server-side code and in client-side code that is only accessible to parties you trust.

Learn about the basics of Graniitti API requests:

Base URL

The base URL for Graniitti API requests is https://<graniitti>/<version>, where <graniitti> is the Graniitti API domain name of your Frosmo Platform instance, and <version> is the API version you're using.

To get the base URL for the latest version in your platform instance:

  1. In the Frosmo Control Panel, select Utilities > Frosmo APIs.
  2. In the Graniitti API section, copy the base URL.

    Getting the base URL for requests

You now have the base URL for sending requests to the Graniitti API.

For more information about Graniitti API versions, see Versioning.

Request types

The API supports the following standard HTTP methods for manipulating resources.

Table: Graniitti API methods

MethodActionExample
GETRetrieve a resource or a collection of resources.
GET /users

GET /users/123
POSTCreate a new resource.
POST /users
PUTUpdate a whole resource.
PUT /users/123
PATCH

Update a portion of a resource.

This method is only used with company settings.

PATCH /companies/455/settings/timezone
DELETEDelete a resource.
DELETE /users/123

Request headers

The API accepts the following headers in a request.

Table: Graniitti API request headers

HeaderDescriptionAllowed values
Content-Type

Media type of the request body.

This field is required for POST and PUT requests.

application/json
Token

Access token for authenticating with the API.

This field is required for all requests.

For instructions on how to get the token, see Authentication.

<access_token>

For more information about the standard HTTP headers, see the header fields registry maintained by IANA.

Request body

For POST, PUT, and PATCH requests, the body must be in the JSON format. If the body is not valid JSON, or if the data model represented by the JSON is incorrect, the API returns a 400 status code in the response.

A single resource is represented as an object. A collection of resources is represented as an array of objects. The following example shows a request body containing a single resource object.

{
  "firstname": "User",
  "lastname": "User",
  "email": "user.user@company.com",
  "password": "8sKJ0688p!",
  "role": "user"
}

Trimming

The API automatically strips the following characters from the beginning and end of all string values in the request body:

  • Carriage return (\r)
  • New line (\n)
  • NUL (\0)
  • Space
  • Tab (\t)
  • Vertical tab (\x0B)

The API uses the PHP trim() function to strip the characters.

The following example shows a request body before and after trimming.

/* Request body sent to the Graniitti API */
{
  "firstname": "   User ",
  "lastname": "User\n",
  "email": "\t\tuser.user@company.com",
  "password": "8sKJ0688p!",
  "role": "user"
}

/* Request body trimmed by the Graniitti API */
{
  "firstname": "User",
  "lastname": "User",
  "email": "user.user@company.com",
  "password": "8sKJ0688p!",
  "role": "user"
}

Query parameters

The API supports the following query parameters for GET requests. You can use the parameters to filter and otherwise process the results returned by the API.

Table: Query parameters for Graniitti API GET requests

ParameterDescriptionExample
<field_name>

Filter results based on resource field values.

For more information, see Filtering with field values.

/users?lastname=user
custom_code

Replace the custom code with a placeholder text string when retrieving the full contents of a custom script with a GET /sites/<site_id>/js request.

For example, GET /sites/1234/js?custom_code=PLACEHOLDER returns the full contents of the custom script but with the custom code replaced by the text "PLACEHOLDER".

The custom_code parameter is only valid for GET /sites/<site_id>/js requests.

When you use the custom_code parameter, the API caches the custom script contents for 60 minutes. Within those 60 minutes, if you use the Graniitti API to make changes to the site that get reflected in the site's custom script, such as updating a cached modification or adding a new placement, and then make another GET /sites/<site_id>/js request with the custom_code parameter, the API returns the cached contents (with the custom code replaced).

If you want to get the latest contents with the changes, first deploy the custom script with a POST /sites/<site_id>/js/export request, and then make the GET /sites/<site_id>/js?custom_code request.

For more information about deploying the custom script, see Custom script update.

/sites/1234/js?custom_code=PLACEHOLDER
fields

Select which fields are included in the response.

For more information, see Selecting which fields to return.

/users?fields=firstname,lastname

fiql

fiql_enc

Use Feed Item Query Language (FIQL) to define advanced results filtering.

The fiql_enc parameter assumes a percent-encoded string value. The API decodes the value before using it to filter results. By comparison, the fiql parameter assumes a non-encoded string value, which the API uses as is. You can use both parameters in the same request.

For more information, see Filtering with FIQL.

/users?fiql=lastname==User

/users?fiql=lastname==User%2C%20Jr

/users?fiql_enc=lastname%3D%3DUser%252C%2520Jr
includes

Embed related resources in the response.

For more information, see Embedding.

/users?includes=companies
page

Specify the number of the page from which to return the results. Specifying this parameter enables pagination of results.

If you specify this parameter, the API returns the results only from the specified page. For example, if you set this parameter to 2, the API returns the results only from page 2, not up to page 2 or starting from page 2.

By default, results are not paginated, and requests that do not use pagination are limited to 10 000 results. If a request finds more than 10 000 results, the request returns an error. In this case, to get the results, use pagination.

For more information, see Paginating.

/products?page=2
per_page

Specify the number of results to return per page. The default is 100 results.

This parameter has no effect unless you also specify the page parameter.

For more information, see Paginating.

/products?page=2&per_page=50
sort

Sort the results by one or more fields.

For more information, see Sorting.

/users?sort=lastname,firstname
  • No labels