Graniitti API: Requests

warning

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, in the header, click your username, and select API Access.

2. In the Graniitti API section, copy the base URL.

   

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

For more information about Graniitti API versions, see Graniitti API: Versioning.

Request types

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

Graniitti API request headers

Method	Action	Example
GET	Retrieve a resource or a collection of resources.	GET /users GET /users/123
POST	Create a new resource.	POST /users
PUT	Update a whole resource.	PUT /users/123
PATCH	Update a portion of a resource. info This method is only used with company settings.	PATCH /companies/455/settings/timezone
DELETE	Delete a resource.	DELETE /users/123

Request headers

The API accepts the following headers in a request.

Graniitti API request headers

Header	Description	Allowed 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 Graniitti API 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.

Query parameters for Graniitti API GET requests

Parameter	Description	Example
<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". info The custom_code parameter is only valid for GET /sites/<site_id>/js requests. note 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 modification whose content is preloaded 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 Updating the custom script with the Graniitti API.	/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. info 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. info 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