NAV Navbar
json

Introduction

Welcome to the Plate REST API documentation. In this documentation you will find a guide on how to use the Plate API.

Available libraries

For the Plate API, a rubygem is available.

API Usage

The following sections describe how to connect to the Plate API.

Connecting to the Plate API

Any application can connect to the Plate API using an HTTP request with a certain method to an endpoint, with some parameters. The resources section of the documentation describes the details of all available endpoints, such as the endpoint itself, the required HTTP method and the permitted/required parameters.

Method

The HTTP method of a request should be one of [GET, PUT, POST, DELETE].

Endpoint

These endpoints (urls) of the API are structured as follows: www.startwithplate.com/api/v2/{specific_path}, where {specific_path} represents a path corresponding to a certain action. {specific_path} could for example be partners/1/companies, so the complete endpoint would be www.startwithplate.com/api/v2/partners/1/companies. This path corresponds to the index of all companies for the partner with id 1.

Parameters

Each HTTP request can contain three types of parameters: URL parameters, Query parameters and POST/PUT parameters.

URL parameters

An URL parameter is one that is part of the endpoint itself. These parameters mostly correspond to an id of a certain resource. The endpoint www.startwithplate.com/api/v2/partners/1/companies contains the URL parameter :partner_id with value 1, indicating that only companies of the partner with id 1 should be returned.

Query parameter

A Query parameter is one that is appended to the endpoint in the form of a query string. They can be used to convey information about for example pagination The endpoint www.startwithplate.com/api/v2/partners/1/companies?pagination_page=3 contains the Query parameter pagination_page with value 3, indicating that the third page of the pagination should be returned.

POST/PUT parameters

{
  "data":{
    "name": "A new name",
    "path": "/some/random/path"
  }
}

A POST/PUT parameter is one that is sent in the body of a POST or PUT request. Plate requires this body to be structured in JSON format. The description of each endpoint in the resources section also describes the accepted POST/PUT parameters.

The example shown aside, shows how to submit the POST parameters name and path.

Authentication and Authorization

To authenticate a request, it has to be accompanied by authentication details. The authentication details consist of 2 parts, a public key and a signature calculated using the secret key. If a request is authenticated correctly, it will also be authorized.

Integration

To create a key pair (a public and a secret key), you have to create a so-called integration in the Plate dashboard. An integration represents an external application that interacts with the Plate API. When you create an integration, you are able to create a key pair.

Authentication procedure

To authenticate a request, two headers have to be sent with the request: the Date header and the Authorization header.

Date header

The Date header should contain the current time, formatted according to RFC 7231. A request will be unauthorized if this date is more than 15 minutes past the time at which the server receives this request.

Authorization header

The Authorization consists of 3 parts: hmac {public_key}:{signature}.

Calculating the signature

The layout of the string to sign of a request

{http_method}
{url_domain}
{url_path}
{query_string}
{http_date}

To calculate the signature of a request, first the string to sign has to be setup. The layout of the string to sign is shown to the right.

An example string to sign (note that paginate_amount and paginate_page are fictional parameters, and only there as an example)

GET
www.startwithplate.com
/api/v2/partners/15/sites
paginate_amount=10&paginate_page=2
Sun, 06 Nov 1994 08:49:37 GMT

The valid Authorization header given the above string to sign is

Authorization hmac mypublickey:FOjhvBsNceYeVNAJtneSLUeYbNO133Gj1sx+aEu7I8A2ixH3VyYpc6PtxGDGVzpG1EPrDaL7sgurV2Q0+8BHDQ==

The string to sign consists of the following parts:

To get the signature, the HMAC based on the string to sign has to be calculated, as defined in RFC 2104, using the SHA512 hash algorithm. The key that is used for the HMAC, is the secret key that corresponds to the public key that is used in the authorization header, alongside the signature. The signature has be send in base64 representation, so not in a hexadecimal representation.

Example

The HMAC of the example string to sign (shown to the right), with a secret key of mysecretkey, would be: FOjhvBsNceYeVNAJtneSLUeYbNO133Gj1sx+aEu7I8A2ixH3VyYpc6PtxGDGVzpG1EPrDaL7sgurV2Q0+8BHDQ==.

So given a key pair with a public key of mypublickey and a secret key of mysecretkey, and a request with:

the valid Authorization header would be:

hmac mypublickey:FOjhvBsNceYeVNAJtneSLUeYbNO133Gj1sx+aEu7I8A2ixH3VyYpc6PtxGDGVzpG1EPrDaL7sgurV2Q0+8BHDQ==

Pagination

To prevent unmanageable response sizes, all index endpoints are paginated. Each page contains a number of records, and if the total number of records exceeds the number of records on a page, a next page will be available.

Pagination response keys

GET {base_url}/site_translations/1/posts returns the following json. Note that total_pages equals 2 since total_records > per_page

{
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 250,
      "total_records": 276,
      "total_pages": 2
    }
  },
  "data": [
    ...
  ]
}

Each index endpoint will return a pagination keys. These will be located in the pagination object inside the meta object in a response. The following keys will be present:

Key Description
page The page returned in the response
per_page The amount of records returned per page.
total_records The total amount of records available.
total_pages The total amount of pages available.

Pagination request keys

GET {base_url}/site_translations/15/posts?page=3&per_page=15 returns the following json. Note that total_pages equals 2 since total_records > per_page

{
  "meta": {
    "pagination": {
      "page": 3,
      "per_page": 15,
      "total_records": 50,
      "total_pages": 4
    }
  },
  "data": [
    ...
  ]
}

To change the pagination parameters, some url parameters can be send with the request. These will for example allow to change the page that is returned in the response, or the number of records that is returned per page. The following pagination keys are accepted:

Key Description Default value Constraints
page The page returned in the response 1 Has to be larger than 0
per_page The amount of records returned per page. 250 Has to be between 1 and 250

Content Objects

Some of the resources available through the Plate API have a dynamic set of content fields. These content fields can be defined through the Plate dashboard. Resources which have such content fields are called content objects. Examples of content objects are site translations, posts, sections and elements. The endpoints for content objects have some specific features/requirements.

Responses for content objects

A GET endpoint for a content object may return JSON as follows:

{
  "data": {
    "id": 1,
    "type": "elements",
    "attributes": {
      "content": {
        "categories": {
          "value": [789],
          "type": "reference",
          "subtype": "posts",
          "content_field_id": 123
        },
        "name": {
          "value": "Pied Piper",
          "type": "string",
          "content_field_id": 456
        }
      },
      ...
    },
    ...
  }
}

For endpoints of content objects, the JSON response is expanded with the values set for the content fields of the content objects.

Consider an element with id=5, having two content fields:

An example response is shown aside.

As can be seen in the example response, the API will return an extra property in the "attributes" objects, named "content", next to the 'standard' attributes. The "content" object in the response contains an object for each of the content fields of the selected object (the element, in the example). Each content field object contains the properties of that content field for the content object.

For each content field, the following properties are returned:

Property Description
value The value of the content field for the selected content object.
type The type of content field. E.g. "string", "array" or "reference".
subtype (optional) The subtype of the content field. Only given for content fields with type "array" or "reference". E.g. "attachments", or "posts".
content_field_id The id of the content_field

Value

The value property can be of different types - it can be a string, integer or array, depending of the type of content field. So the type property can be used to deduce the meaning of the value found in the value property.

For reference fields, the value property will be an array of numbers. These numbers are ID's of referenced resources for the content field. The subtype property will indicate what kind of resource is selected/referenced.

For array fields, the value property will be an array of numbers or strings, depending on the subtype property. If the subtype property equals attachments, the value property will be an array of numbers, representing attachments. If the subtype property equals text, then the value property will be an array of strings, which is the actual value of the content field.

Requests for content objects

A request to a POST endpoint for a content object may contain data as follows:

{
  "data": {
    ...
    "name": "A name for the new element",
    "categories": [
      {
        "id": 25
      },
      {
        "title": "A title for a newly created reference post"
        ...
      }
    ]
  }
}

For PUT/POST endpoints of content objects, the data sent with the request also can contain data for the content fields for content objects. Consider creating an element with a post type that has the following content fields:

An example of request data is shown aside.

As can be seen in the example, for each content field an object or value is provided in the request data.

Positionable Objects

Some of the resources available through the Plate API, are so called positionable objects. These objects can be positioned within their parent. For example, sections can be positioned within a post, and rows within a section.

Inside a specific parent, each positionable object has a unique, sequential position. This means that if there are 4 positionable objects inside 1 parent, each object will have a property position with value equal to one of [1,2,3,4].

For example, if there are 3 sections inside a post:

The following constraint for values of the position attribute of a positionable object holds:

A GET endpoint for a positionable object may return JSON as follows:

{
  "data": {
    "id": 1,
    "type": "elements",
    "attributes": {
      "position": 1,
      ...
    },
    ...
  }
}

Responses for positionable objects

The current position of a positionable object is returned in responses, as a property inside the attributes object. See the example aside.

Requests for positionable objects

A request to a POST endpoint for a positionable object may contain data as follows:

{
  "data": {
    "position": 2,
    ...
  }
}

The position of a positionable object can be set in POST/PUT requests. This can be done by giving the position property inside the POST/PUT parameters. See the example aside.

The values given for the position property have to fall within the constraint on the position.

Errors

For example when a partner with id=1 does not exist: GET {base_url}/partners/1

{
  "errors": [
    {
      "id": 1,
      "resource_type": "partner",
      "status": "404",
      "code": "not-found",
      "title": "Partner not found",
      "detail": "A partner with id=1 could not be found"
    }
  ]
}

If a request is invalid, Plate will return a corresponding HTTP status, accompanied by clarifying error messages. These error messages will be send in the JSON response, in the errors array. (See example) These errors can contain the following keys:

Key Description
id The request-specified id of the resource that could not be found
resource_type The kind of resource that could not be found. E.g. "partner" or "site"
status The HTTP status code applicable to this problem, as a string value
code An human-readable version of the status
title A short description of the problem
detail A human-readable explanation of the occurred problem
messages An array of problem-specific messages. E.g. which validations failed

The following errors can be returned by Plate:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Wrong authentication details provided
403 Forbidden -- Forbidden request
404 Not Found -- The specified resource could not be found.
422 Unprocessable entity
429 Too Many Requests -- You're requesting too many requests.
500 Internal Server Error -- We had a problem with our server. Try again later.

400 Bad Request

The provided request does not match with the required syntax. Read the documentation for the valid syntax.

401 Unauthorized

The provided authentication details do not match any valid integration according to the authentication requirements. Please follow these requirements with an activated integration key.

403 Forbidden

The request was understood, but the authenticated integration is not allowed to perform this action.

404 Not Found

One or more resources specified in the request could not be found.

422 Unprocessable entity

The request was understood and authorized, but the data provided does not match the requirements. For example one of the validations of a provided content field was not matched, or a required attribute was not given.

429 Too Many Requests

The server received too many requests, please slow down the rate of requests. The rate limiting is implemented using the Sliding Log mechanism. This means that for each partition in time, a certain amount of requests is allowed. Currently, the allowed number of requests is 50 requests per 5000 milliseconds.

This means that the following sequence of requests will exceed the rate limit:

Since at t=4, more than 50 request have been executed in the past 5 seconds.

However the following sequence of requests will not exceed the rate limit:

Since at every value for t, the amount of requests in the past 5 seconds is at most 50. (At t=4, the total count in the previous 5 seconds is 48, at t=5, 49, and at t=6, 49 as well)

500 Internal Server Error

An error occurred while executing your request. Please try again later, or contact info@getplate.com for help.

Resources

Partners

Get specific partner

GET {base_url}/partners/1 returns JSON structured like this:

{
  "data": {
    "id": 1,
    "type": "partners",
    "attributes": {
      "name": "Partner Name 1"
    },
    "relations": {}
  }
}

This endpoint retrieves a specific partner.

HTTP Request

GET {base_url}/partners/:id

URL Parameters

Parameter Description
:id The id of the partner to retrieve

Update partner

An example of valid JSON PUT parameters

{
  "data": {
"name": "New Partner name" } }

PUT {base_url}/partners/1 with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 1,
    "type": "partners",
    "attributes": {
      "name": "New Partner name"
    },
    "relations": {}
  }
}

This endpoint updates a specific partner.

HTTP Request

PUT {base_url}/partners/:id

URL Parameters

Parameter Description
:id The id of the partner to update

PUT Parameters

Parameter Description Constraints
name The new name for this partner String. Not null

Companies

Get all companies

GET {base_url}/partners/1/companies/ returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "type": "companies",
      "attributes": {
        "name": "Company Name 1",
        "street_name": "Somestreet",
        "street_no": "5",
        "street_suffix": "a",
        "city": "Ede",
        "zipcode": "6734 AT",
        "country": "Netherlands",
        "phone": "+3123456789",
        "kvk_number": "0123456789",
        "vat_number": "9876543210",
        "invoice_contact_first_name": "Johannes",
        "invoice_contact_last_name": "Pleet",
        "invoice_contact_email": "johannes@getplate.com"
      },
      "relations": {
        "partner_id": 1
      }
    },
    {
      "id": 2,
      "type": "companies",
      "attributes": {
        "name": "Company Name 2",
        "street_name": "Somestreet",
        "street_no": "5",
        "street_suffix": "a",
        "city": "Ede",
        "zipcode": "6734 AT",
        "country": "Netherlands",
        "phone": "+3123456789",
        "kvk_number": "0123456789",
        "vat_number": "9876543210",
        "invoice_contact_first_name": "Johannes",
        "invoice_contact_last_name": "Pleet",
        "invoice_contact_email": "johannes@getplate.com"
      },
      "relations": {
        "partner_id": 1
      }
    }
  ]
}

This endpoint retrieves all companies in a specific partner.

HTTP Request

GET {base_url}/partners/:partner_id/companies

URL Parameters

Parameter Description
:partner_id The id of the partner to which the companies belong

Get specific Company

GET {base_url}/partners/1/companies/1 returns JSON structured like this:

{
  "data": {
    "id": 1,
    "type": "companies",
    "attributes": {
      "name": "Company Name 1",
      "street_name": "Somestreet",
      "street_no": "5",
      "street_suffix": "a",
      "city": "Ede",
      "zipcode": "6734 AT",
      "country": "Netherlands",
      "phone": "+3123456789",
      "kvk_number": "0123456789",
      "vat_number": "9876543210",
      "invoice_contact_first_name": "Johannes",
      "invoice_contact_last_name": "Pleet",
      "invoice_contact_email": "johannes@getplate.com"
    },
    "relations": {
      "partner_id": 1
    }
  }
}

This endpoint retrieves a specific company.

HTTP Request

GET {base_url}/companies/:id

URL Parameters

Parameter Description
:id The id of the company to retrieve

Alternative endpoints

Alternative endpoints are:

Create company

An example of valid JSON POST parameters

{
  "data": {    
    "name": "Created Company Name 1",
  }
}

POST {base_url}/partners/1/companies with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 1,
    "type": "companies",
    "attributes": {
      "name": "Created Company Name 1",
      "street_name": "",
      "street_no": "",
      "street_suffix": "",
      "city": "",
      "zipcode": "",
      "country": "",
      "phone": "",
      "kvk_number": "",
      "vat_number": "",
      "invoice_contact_first_name": "",
      "invoice_contact_last_name": "",
      "invoice_contact_email": ""
    },
    "relations": {
      "partner_id": 1
    }
  }
}

This endpoint creates a company.

HTTP Request

POST {base_url}/partners/:partner_id/companies

URL Parameters

Parameter Description
:partner_id The id of the partner to which the new company belongs

POST Parameters

Parameter Description Constraints
name The name for the new company String. Not null
street_name The street name for the new company
street_no The street number for the new company
street_suffix The street suffix for the new company
city The city for the new company
zipcode The zipcode for the new company
country The country for the new company
phone The phone number for this company
kvk_number The kvk number for the new company
vat_number The vat number for the new company
invoice_contact_first_name The first name for the invoice contact for the new company
invoice_contact_last_name The last name for the invoice contact for the new company
invoice_contact_email The email address for the invoice contact for the new company

Update company

An example of valid JSON PUT parameters

{
  "data": {    
    "name": "New Company name"
  }
}

PUT {base_url}/partners/1/companies/1 with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 1,
    "type": "companies",
    "attributes": {
      "name": "New Company name",
      "street_name": "Somestreet",
      "street_no": "5",
      "street_suffix": "a",
      "city": "Ede",
      "zipcode": "6734 AT",
      "country": "Netherlands",
      "phone": "+3123456789",
      "kvk_number": "0123456789",
      "vat_number": "9876543210",
      "invoice_contact_first_name": "Johannes",
      "invoice_contact_last_name": "Pleet",
      "invoice_contact_email": "johannes@getplate.com"
    },
    "relations": {
      "partner_id": 1
    }
  }
}

This endpoint updates a specific company.

HTTP Request

PUT {base_url}/companies/:id

URL Parameters

Parameter Description
:partner_id The id of the partner to which the updated company belongs
:id The id of the company to update

PUT Parameters

Parameter Description Constraints
name The new name for this company Not null.
street_name The new street name for this company Not null.
street_no The new street number for this company Not null.
street_suffix The new street suffix for this company
city The new city for this company Not null.
zipcode The new zipcode for this company Not null.
country The new country for this company Not null.
phone The new phone number for this company
kvk_number The new kvk number for this company Not null.
vat_number The new vat number for this company Not null.
invoice_contact_first_name The new first name for the invoice contact for this company Not null.
invoice_contact_last_name The new last name for the invoice contact for this company Not null.
invoice_contact_email The new email address for the invoice contact for this company Not null.

Alternative endpoints

Alternative endpoints are:

Delete company

DELETE {base_url}/partners/1/companies/1 returns JSON structured like this:

{
  "data": {
    "id": 1,
    "name": "Company Name 1"
  }
}

This endpoint deletes a specific company.

HTTP Request

DELETE {base_url}/companies/:id

URL Parameters

Parameter Description
:partner_id The id of the partner to which the delete company belongs
:id The id of the company to delete

Constraints

This endpoint has the following constraints:

Alternative endpoints

Alternative endpoints are:

Sites

Get all sites

GET {base_url}/partners/1/companies/1/sites/ returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "type": "sites",
      "attributes" : {
        "name": "Site name 1",
        "languages": "nl,en",
        "main_language": "nl",
        "param_key": "aea00cde61",
        "technical_contact_name": "David",
        "technical_contact_email": "david@getplate.com",
        "status": "creating",
        "is_theme_base_site": false
      },
      "relations" : {
        "company_id": 1,
        "theme_id": 1
      }
    },
    {
      "id": 2,
      "type": "sites",
      "attributes" : {
        "name": "Site name 2",
        "languages": "nl,en,de",
        "main_language": "nl",
        "param_key": "aec91acccc",
        "technical_contact_name": "Kobus",
        "technical_contact_email": "kobus@getplate.com",
        "status": "ready",
        "is_theme_base_site": false
      },
      "relations": {
        "company_id": 1,
        "theme_id": 123,
      }
    }
  ]
}

This endpoint retrieves all sites in a specific company.

HTTP Request

GET {base_url}/companies/:company_id/sites

URL Parameters

Parameter Description
:company_id The id of the company to which the sites belong
:partner_id The id of the partner to which the sites belong

Alternative endpoints

Alternative endpoints are:

Get specific Site

GET {base_url}/companies/1/sites/2 returns JSON structured like this:

{
  "data": {
    "id": 2,
    "type": "sites",
    "attributes" : {
      "name": "Site name 2",
      "languages": "nl,en,de",
      "main_language": "nl",
      "param_key": "aec91acccc",
      "technical_contact_name": "Kobus",
      "technical_contact_email": "kobus@getplate.com",
      "status": "ready",
      "is_theme_base_site": false
    },
    "relations" : {
      "theme_id": 123,
      "company_id": 1
    }
  }
}

This endpoint retrieves a specific site.

HTTP Request

GET {base_url}/sites/:id

URL Parameters

Parameter Description
:company_id The id of the company of the site to retrieve
:id The id of the site to retrieve

Alternative endpoints

Alternative endpoints are:

Create site

An example of valid JSON POST parameters

{
  "data": {    
    "name": "Created site",
    "theme_id": 1,
    "languages": "nl,en",
    "main_language": "en",
    "technical_contact_name": "Pieter",
    "technical_contact_email": "pieter@getplate.com",
    "initial_subdomain": "my-created-site"
  }
}

POST {base_url}/companies/3/sites with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "sites",
    "attributes": {
      "name": "Created site",
      "languages": "nl,en",
      "main_language": "en",
      "param_key": "aec91acccc",
      "technical_contact_name": "Pieter",
      "technical_contact_email": "pieter@getplate.com",
      "status": "creating",
      "is_theme_base_site": false
    },
    "relations": {
      "theme_id": 1,
      "company_id": 3,
    }
  }
}

This endpoint creates a site.

HTTP Request

POST {base_url}/companies/:company_id/sites

URL Parameters

Parameter Description
:company_id The id of the company to which the new site belongs

POST Parameters

Parameter Description Constraints
name The name of the new site Required
seo_title The SEO title of the new site
seo_description The SEO description of the new site
languages The languages of the new site Required. Has to be comma-seperated string of language codes
main_language The main language of the new site Required. Has to be in languages
theme_id The id of the theme that will be installed on the new site. Has to correspond to an existing theme
technical_contact_name The name of the technical contact of the new site.
technical_contact_email The email of the technical contact of the new site.
initial_subdomain The initial subdomain of this site Required. Has to be an url-safe string.

Update site

An example of valid JSON PUT parameters

{
  "data": {    
    "name": "New name"
  }
}

PUT {base_url}/companies/3/sites/3 with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "sites",
    "attributes": {
      "name": "New name",
      "languages": "nl,en",
      "main_language": "en",
      "param_key": "aec91acccc",
      "technical_contact_name": "Pieter",
      "technical_contact_email": "pieter@getplate.com",
      "status": "ready",
      "is_theme_base_site": false
    },
    "relations": {
      "theme_id": 1,
      "company_id": 3,
    }
  }
}

This endpoint updates a site.

HTTP Request

PUT {base_url}/sites/:id

URL Parameters

Parameter Description
:company_id The id of the company to which the site to update belongs
:id The id of the site to update

PUT Parameters

Parameter Description Constraints
name The new name of the site to update Not null
seo_title The new SEO title of the site to update
seo_description The new SEO description of the site to update
languages The new languages of the site to update Not null. Has to be comma-seperated string of language codes
main_language The new main language of the site to update Not null. Has to be in languages
technical_contact_name The new name of the technical contact of the site to update.
technical_contact_email The new email of the technical contact of the site to update.
enable_theme_updates Whether this site should be linked to updates of its theme Either true or false

Alternative endpoints

Alternative endpoints are:

Delete site

DELETE {base_url}/companies/1/sites/3 returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "sites",
    "attributes": {
      "name": "New name",
      "languages": "nl,en",
      "main_language": "en",
      "param_key": "aec91acccc",
      "technical_contact_name": "Pieter",
      "technical_contact_email": "pieter@getplate.com",
      "status": "ready",
      "is_theme_base_site": false
    },
    "relations": {
      "theme_id": 1,
      "company_id": 3,
    }
  }
}

This endpoint deletes a specific company.

HTTP Request

DELETE {base_url}/sites/:id

URL Parameters

Parameter Description
:company_id The id of the company to which the delete site belongs
:id The id of the site to delete

Alternative endpoints

Alternative endpoints are:

Themes

Get all themes

GET {base_url}/partners/1/themes/ returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "type": "themes",
      "attributes" : {
        "name": "Theme name 1",
        "languages": "nl,en",
        "main_language": "nl",
        "status": "creating"
      },
      "relations" : {
        "partner_id": 1,
        "site_id": 22
      }
    },
    {
      "id": 2,
      "type": "themes",
      "attributes" : {
        "name": "Theme name 2",
        "languages": "nl",
        "main_language": "nl",
        "status": "unpublished"
      },
      "relations" : {
        "partner_id": 1,
        "site_id": 23
      }
    }
  ]
}

This endpoint retrieves all themes for a specific partner

HTTP Request

GET {base_url}/partners/:partner_id/themes

URL Parameters

Parameter Description
:partner_id The id of the partner to which the themes belong

Get specific Theme

GET {base_url}/partners/1/themes/2 returns JSON structured like this:

{
  "data": {
    "id": 2,
    "type": "themes",
    "attributes" : {
      "name": "Theme name 2",
      "languages": "nl",
      "main_language": "nl",
      "status": "unpublished"
    },
    "relations" : {
      "partner_id": 1,
      "site_id": 23
    }
  }
}

This endpoint retrieves a specific Theme.

HTTP Request

GET {base_url}/partners/:partner_id/themes/:id

Alternative endpoints

Alternative endpoints are:

URL Parameters

Parameter Description
:partner_id The id of the partner of the theme to retrieve
:id The id of the company to retrieve

Create theme

An example of valid JSON POST parameters

{
  "data": {    
    "name": "Created theme",
    "copy_from_theme_id": 1,
    "languages": "nl,de",
    "main_language": "de",
    "initial_subdomain": "my-created-theme-example-site"
  }
}

POST {base_url}/partners/3/themes with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 5,
    "type": "themes",
    "attributes" : {
      "name": "Created theme",
      "languages": "nl,de",
      "main_language": "de",
      "status": "creating"
    },
    "relations" : {
      "partner_id": 3,
      "site_id": 29
    }
  }
}

This endpoint creates a theme.

HTTP Request

POST {base_url}/partners/:partner_id/themes

URL Parameters

Parameter Description
:partner_id The id of the partner to which the new theme belongs

POST Parameters

Parameter Description Constraints
name The name of the new theme Required
languages The languages of the new theme Required. Has to be comma-seperated string of language codes
main_language The main language of the new theme Required. Has to be in languages
copy_from_theme_id The id of the theme that will be installed on the new theme. Has to correspond to an existing theme
initial_subdomain The subdomain where this theme will be visible Required. Has to be an url-safe string.

Update theme

An example of valid JSON PUT parameters

{
  "data": {    
    "name": "New name"
  }
}

PUT {base_url}/partners/3/themes/5 with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 5,
    "type": "themes",
    "attributes" : {
      "name": "New name",
      "languages": "nl,de",
      "main_language": "de",
      "status": "creating"
    },
    "relations" : {
      "partner_id": 3,
      "site_id": 29
    }
  }
}

This endpoint updates a theme.

HTTP Request

PUT {base_url}/themes/:id

URL Parameters

Parameter Description
:partner_id The id of the partner to which the theme to update belongs
:id The id of the theme to update

PUT Parameters

Parameter Description Constraints
name The new name of the theme
languages The new languages of the theme Has to be comma-seperated string of language codes
main_language The new main language of the theme Has to be in languages

Alternative endpoints

Alternative endpoints are:

Delete theme

DELETE {base_url}/partners/3/themes/5 returns JSON structured like this:

{
  "data": {
    "id": 5,
    "type": "themes",
    "attributes" : {
      "name": "New name",
      "languages": "nl,de",
      "main_language": "de",
      "status": "creating"
    },
    "relations" : {
      "partner_id": 3,
      "site_id": 29
    }
  }
}

This endpoint deletes a specific theme.

HTTP Request

DELETE {base_url}/themes/:id

URL Parameters

Parameter Description
:partner_id The id of the partner to which the theme to delete belongs
:id The id of the theme to delete

Alternative endpoints

Alternative endpoints are:

Theme files

Get all theme files

GET {base_url}/sites/1/theme_files/ returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "type": "theme_files",
      "attributes" : {
        "etag": "a2b67bf1906313e9f98c3c0a2bbb7b4c",
        "path": "posts",
        "file_name": "index",
        "extension": "plate",
      },
      "relations" : {
        "site_id": 1,
      }
    },
    {
      "id": 2,
      "type": "theme_files",
      "attributes" : {
        "etag": "ef8192015354713e9f98c3c0a2ec76ec",
        "path": "posts",
        "file_name": "show",
        "extension": "plate",
      },
      "relations" : {
        "site_id": 1,
      }
    }
  ]
}

This endpoint retrieves all theme files for a specific site

HTTP Request

GET {base_url}/sites/:site_id/theme_files

URL Parameters

Parameter Description
:site_id The id of the site to which the theme files belong

Download all theme files

This endpoint returns all theme files of a specific site packed together in a zip file.

HTTP Request

GET {base_url}/sites/:site_id/theme_files/download

URL Parameters

Parameter Description
:site_id The id of the site of the theme files to download

Get specific theme file

GET {base_url}/sites/1/theme_files/2 returns JSON structured like this:

{
  "data": {
    "id": 2,
    "type": "theme_files",
    "attributes" : {
      "etag": "ef8192015354713e9f98c3c0a2ec76ec",
      "path": "posts",
      "file_name": "show",
      "extension": "plate",
    },
    "relations" : {
      "site_id": 1,
    }
  }
}

This endpoint retrieves details about a specific theme file, but does not return the actual content of the theme file

HTTP Request

GET {base_url}/sites/:site_id/theme_files/:id

URL Parameters

Parameter Description
:site_id The id of the site of the theme_file to retrieve
:id The id of the theme_file to retrieve

Download specific theme file

This endpoint returns a specific theme file as a file.

HTTP Request

GET {base_url}/sites/:site_id/theme_files/:id/download

URL Parameters

Parameter Description
:site_id The id of the site of the theme_file to download
:id The id of the theme_file to download

Create theme file

An example of a valid HTTP request body, given the header Content-type: multipart/formdata; boundary: arandomuniquestring098123

--arandomuniquestring098123
Content-Disposition: form-data; name="path"

posts --arandomuniquestring098123 Content-Disposition: form-data; name="file" filename="index.plate" Content-Type: text/plain

... contents of the file 'index.plate' ... --arandomuniquestring098123-

POST {base_url}/site/1/theme_files with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 2,
    "type": "theme_files",
    "attributes" : {
      "etag": "ef8192015354713e9f98c3c0a2ec76ec",
      "path": "posts",
      "file_name": "index",
      "extension": "plate",
    },
    "relations" : {
      "site_id": 1,
    }
  }
}

This endpoint is used to upload a new theme file. This endpoint expects a request with Content-type: multipart/form-data, boundary={boundary-key}, following the multipart/form-data principle as defined in RFC 7578 and shown in RFC 1867.

All POST parameters should also be sent according to the multipart principle, that is, each variable should have its own part in the request body. To the right an example of a valid HTTP request is shown.

HTTP Request

POST {base_url}/sites/:site_id/theme_files

URL Parameters

Parameter Description
:site_id The id of the site to which the new theme_file belongs

POST Parameters

Parameter Description Constraints
path The path where the new theme_file is situated in the theme or site Has to be a valid path
file The new theme file. Required

Update theme file

An example of valid JSON PUT parameters

{
  "data": {    
    "path": "pages"
    "file_name": "_sidebar"
  }
}

PUT {base_url}/sites/1/theme_files/2 with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 2,
    "type": "theme_files",
    "attributes" : {
      "etag": "ef8192015354713e9f98c3c0a2ec76ec",
      "path": "pages",
      "file_name": "_sidebar",
      "extension": "plate",
    },
    "relations" : {
      "site_id": 1,
    }
  }
}

This endpoint updates a theme file.

HTTP Request

PUT {base_url}/sites/:site_id/theme_files/:id

URL Parameters

Parameter Description
:site_id The id of the site to which the theme file to update belongs
:id The id of the theme file to update

PUT Parameters

Parameter Description Constraints
file_name The new name of the theme file Not null
path The new path of the theme file

Delete theme file

DELETE {base_url}/sites/1/theme_files/2 returns JSON structured like this:

{
  "data": {
    "id": 2,
    "type": "theme_files",
    "attributes" : {
      "etag": "ef8192015354713e9f98c3c0a2ec76ec",
      "path": "pages",
      "file_name": "_sidebar",
      "extension": "plate",
    },
    "relations" : {
      "site_id": 1,
    }
  }
}

This endpoint deletes a specific theme file.

HTTP Request

DELETE {base_url}/sites/:site_id/theme_files/:id

URL Parameters

Parameter Description
:site_id The id of the site to which the theme file to update belongs
:id The id of the theme file to update

Attachment Folders

Get all attachment folders

GET {base_url}/sites/1/attachment_folders/ returns JSON structured like this:

{
  "data": [
    {
      "id": 3,
      "type": "attachment_folders",
      "attributes" : {
        "name": "Folder name 3"
}, "relations" : { "site_id": 1 } }, { "id": 3, "type": "attachment_folders", "attributes" : { "name": "Folder name 3"
}, "relations" : { "site_id": 1 } } ] }

This endpoint retrieves all attachment folders for a specific site

HTTP Request

GET {base_url}/sites/:site_id/attachment_folders

URL Parameters

Parameter Description
:site_id The id of the site to which the attachment folder belong

Get specific attachment folder

GET {base_url}/attachment_folders/3 returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "attachment_folders",
    "attributes" : {
      "name": "Folder name 3"
}, "relations" : { "site_id": 1 } } }

This endpoint retrieves a specific attachment folder.

HTTP Request

GET {base_url}/attachment_folders/:id

URL Parameters

Parameter Description
:site_id The id of the site of the attachment folder to retrieve
:id The id of the attachment folder to retrieve

Alternative endpoints

Alternative endpoints are:

Create attachment folder

An example of valid JSON POST parameters

{
  "data": {    
    "name": "Created Folder",
  }
}

POST {base_url}/sites/1/attachment_folders with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "attachment_folders",
    "attributes" : {
      "name": "Created Folder"        
    },
    "relations" : {
      "site_id": 1
    }
  }
}

This endpoint creates a attachment folder.

HTTP Request

POST {base_url}/sites/:site_id/attachment_folders

URL Parameters

Parameter Description
:site_id The id of the site to which the new attachment folder belongs

POST Parameters

Parameter Description Constraints
name The name of the folder Not null. Required.

Update attachment folders

An example of valid JSON PUT parameters

{
  "data": {    
    "name": "A new foldername"
  }
}

PUT {base_url}/attachment_folders/3 with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "attachment_folders",
    "attributes" : {
      "name": "A new foldername"        
    },
    "relations" : {
      "site_id": 1
    }
  }
}

This endpoint updates a site.

HTTP Request

PUT {base_url}/attachment_folders/:id

URL Parameters

Parameter Description
:site_id The id of the site of the attachment folder to retrieve
:id The id of the attachment folder to retrieve

PUT Parameters

Parameter Description Constraints
name The name of the folder Not null.

Alternative endpoints

Alternative endpoints are:

Delete attachment folder

DELETE {base_url}/attachment_folders/1 returns JSON structured like this:

{
  "data": {
    "id": 1,
    "type": "attachment_folders",
    "attributes" : {
      "name": "The deleted folder"        
    },
    "relations" : {
      "site_id": 1
    }
  }
}

This endpoint deletes a specific attachment folder.

HTTP Request

DELETE {base_url}/attachment_folders/:id

URL Parameters

Parameter Description
:site_id The id of the site to which the delete attachment folder belongs
:id The id of the attachment folder to delete

Alternative endpoints

Alternative endpoints are:

Attachment

Get all attachments

GET {base_url}/sites/1/attachments/ returns JSON structured like this:

{
  "data": [
    {
      "id": 3,
      "type": "attachments",
      "attributes" : {
        "file_name": "some_image.jpg",
        "size": 12391,
        "title": "An image"
      },
      "relations" : {
        "site_id": 1,
        "attachment_folder_id": 2
      }
    },
    {
      "id": 4,
      "type": "attachments",
      "attributes" : {
        "file_name": "other_image.jpg",
        "size": 2002,
        "title": "Another image"
      },
      "relations" : {
        "site_id": 1,
        "attachment_folder_id": null
      }
    }
  ]
}

This endpoint retrieves all attachments for a specific site

HTTP Request

GET {base_url}/sites/:site_id/attachments

URL Parameters

Parameter Description
:site_id The id of the site to which the attachments belong
:attachment_folder_id The id of the attachment folder to which the attachments belong

Alternative endpoints

Alternative endpoints are:

Get specific attachment

GET {base_url}/sites/1/attachments/3 returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "attachments",
    "attributes" : {
      "file_name": "some_image.jpg",
      "size": 12391,
      "title": "An image"
    },
    "relations" : {
      "site_id": 1,
      "attachment_folder_id": 2
    }
  }
}

This endpoint retrieves information about a specific attachment, but does not return the actual content of the attachment

HTTP Request

GET {base_url}/attachments/:id

URL Parameters

Parameter Description
:site_id The id of the site of the attachment to retrieve
:id The id of the attachment to retrieve
:attachment_folder_id The id of the attachment folder to which the attachments belong

Alternative endpoints

Alternative endpoints are:

Download specific attachment

This endpoint returns a specific attachment as a file.

HTTP Request

GET {base_url}/attachments/:id/download

Alternative endpoints

Alternative endpoints are:

URL Parameters

Parameter Description
:site_id The id of the site of the attachment to retrieve
:id The id of the attachment to retrieve
:attachment_folder_id The id of the attachment folder to which the attachments belong

Create attachment

An example of a valid HTTP request body, given the header Content-type: multipart/formdata; boundary: arandomuniquestring098123

--arandomuniquestring098123
Content-Disposition: form-data; name="title"

A title describing this attachment
--arandomuniquestring098123
Content-Disposition: form-data; name="file" filename="plate.png"
Content-Type: image/png

 ... contents of the file 'plate.png' ...
--arandomuniquestring098123-

POST {base_url}/site/1/attachments with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 5,
    "type": "attachments",
    "attributes" : {
      "file_name": "plate.png",
      "size": 12391,
      "title": "A title describing this attachment"
    },
    "relations" : {
      "site_id": 1,
      "attachment_folder_id": 2
    }
  }
}

This endpoint is used to upload a new attachment. This endpoint expects a request with Content-type: multipart/form-data, boundary={boundary-key}, following the multipart/form-data principle as defined in RFC 7578 and shown in RFC 1867.

All POST parameters should also be sent according to the multipart principle, that is, each variable should have its own part in the request body. To the right an example of a valid HTTP request is shown.

HTTP Request

POST {base_url}/sites/:site_id/attachments

URL Parameters

Parameter Description
:site_id The id of the site to which the new theme_file belongs
:theme_id The id of the theme to which the new theme_file belongs

POST Parameters

Parameter Description Constraints
title The title of the new attachment Not null.
file The new attachment. Required

Alternative endpoints

Alternative endpoints are:

Update attachments

An example of valid JSON PUT parameters

{
  "data": {    
    "title": "A new attachment_title"
  }
}

PUT {base_url}/sites/1/attachments/5 with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 5,
    "type": "attachments",
    "attributes" : {
      "file_name": "plate.png",
      "size": 12391,
      "title": "A new attachment_title"
    },
    "relations" : {
      "site_id": 1,
      "attachment_folder_id": 2
    }
  }
}

This endpoint updates a site.

HTTP Request

PUT {base_url}/attachments/:id

URL Parameters

Parameter Description
:site_id The id of the site of the attachment to retrieve
:id The id of the attachment to retrieve
:attachment_folder_id The id of the attachment folder to which the attachments belong

PUT Parameters

Parameter Description Constraints
title The title of the updated attachment Not null.
attachment_folder_id The id of the attachment folder to which the updated attachment belongs Id of an existing attachment folder.

Alternative endpoints

Alternative endpoints are:

Delete attachment

DELETE {base_url}/sites/1/attachments/5 returns JSON structured like this:

{
  "data": {
    "id": 5,
    "type": "attachments",
    "attributes" : {
      "file_name": "plate.png",
      "size": 12391,
      "title": "A new attachment_title"
    },
    "relations" : {
      "site_id": 1,
      "attachment_folder_id": 2
    }
  }
}

This endpoint deletes a specific attachment.

HTTP Request

DELETE {base_url}/attachments/:id

URL Parameters

Parameter Description
:site_id The id of the site of the attachment to retrieve
:id The id of the attachment to retrieve
:attachment_folder_id The id of the attachment folder to which the attachments belong

Alternative endpoints

Alternative endpoints are:

Form Messages

Plate allows to receive form messages using the liquid form tag. These form messages can be retrieved using the following endpoints.

The response not only contains the content, the fields submitted in a form messages, but also sent_from_object which represent the content object that contains the form where the form message was sent from, and also the url of the page where the form was sent from, in sent_from_url.

Note that sent_from_object might be null if the object that contained the form no longer exists.

Get all form messages

GET {base_url}/sites/1/form_messages/ returns JSON structured like this:

{
  "data": [
    {
      "id": 2,
      "type": "form_messages",
      "attributes": {
        "content": {
          "form_field_1": "A filled in form field",
          "some_other_form_field": "an@example.email"
        },
        "sent_from_object": {
          "type": "elements",
          "id": 12
        },
        "sent_from_url": "/contact"
      },
      "relations": {
          "site_id": 1
      }
    },
    {
      "id": 3,
      "type": "form_messages",
      "attributes": {
        "content": {
          "form_field_1": "Another fill",
          "some_other_form_field": "my@sneaky.email"
        },
        "sent_from_object": null,
        "sent_from_url": "/contact"
      },
      "relations": {
          "site_id": 1
      }
    }
  ]
}

This endpoint retrieves all form messages for a specific site

HTTP Request

GET {base_url}/sites/:site_id/form_messages

URL Parameters

Parameter Description
:site_id The id of the site to which the form message belong

Get specific form message

GET {base_url}/form_messages/3 returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "form_messages",
    "attributes": {
      "content": {
        "form_field_1": "A filled in form field",
        "some_other_form_field": "an@example.email"
      },
      "sent_from_object": {
        "type": "elements",
        "id": 12
      },
      "sent_from_url": "/contact"
    },
    "relations": {
        "site_id": 1
    }
  }
}

This endpoint retrieves a specific form message.

HTTP Request

GET {base_url}/form_messages/:id

URL Parameters

Parameter Description
:site_id The id of the site of the form message to retrieve
:id The id of the form message to retrieve

Alternative endpoints

Alternative endpoints are:

Delete form message

DELETE {base_url/form_messages/2 returns JSON structured like this:

{
  "data": {
    "id": 2,
    "type": "form_messages",
    "attributes": {
      "content": {
        "form_field_1": "A filled in form field",
        "some_other_form_field": "an@example.email"
      },
      "sent_from_object": {
        "type": "elements",
        "id": 12
      },
      "sent_from_url": "/contact"
    },
    "relations": {
        "site_id": 1
    }
  }
}

This endpoint deletes a specific form message.

HTTP Request

DELETE {base_url}/form_messages/:id

URL Parameters

Parameter Description
:site_id The id of the site to which the delete form message belongs
:id The id of the form message to delete

Alternative endpoints

Alternative endpoints are:

Redirects

Get all redirects

GET {base_url}/posts/1/redirects/ returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "type": "redirects",
      "attributes": {
        "from_url": "/some_old/path/here"
      },
      "relations": {
        "post_id": 1
      }
    },
    {
      "id": 2,
      "type": "redirects",
      "attributes": {
        "from_url": "/some_other/path/there"
      },
      "relations": {
        "post_id": 1
      }
    }
  ]
}

This endpoint retrieves all redirects in a specific post.

HTTP Request

GET {base_url}/posts/:post_id/redirects

URL Parameters

Parameter Description
:post_id The id of the post to which the redirects belong

Get specific Redirect

GET {base_url}/posts/1/redirects/1 returns JSON structured like this:

{
  "data": {
    "id": 1,
    "type": "redirects",
    "attributes": {
      "from_url": "/some_old/path/here"
    },
    "relations": {
      "post_id": 1
    }
  }
}

This endpoint retrieves a specific redirect.

HTTP Request

GET {base_url}/redirects/:id

URL Parameters

Parameter Description
:id The id of the redirect to retrieve

Alternative endpoints

Alternative endpoints are:

Create redirect

An example of valid JSON POST parameters

{
  "data": {    
    "from_url": "/an/old/path",
  }
}

POST {base_url}/posts/1/redirects with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "redirects",
    "attributes": {
      "from_url": "/an/old/path"
    },
    "relations": {
      "post_id": 1
    }
  }
}

This endpoint creates a redirect.

HTTP Request

POST {base_url}/posts/:post_id/redirects

URL Parameters

Parameter Description
:post_id The id of the post to which the new redirect belongs

POST Parameters

Parameter Description Constraints
from_url The path which is redirected Is a valid http path.

Update redirect

An example of valid JSON PUT parameters

{
  "data": {    
    "from_url": "/a/new/path",
  }
}

PUT {base_url}/posts/1/redirects/1 with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 1,
    "type": "redirects",
    "attributes": {
      "from_url": "/a/new/path"
    },
    "relations": {
      "post_id": 1
    }
  }
}

This endpoint updates a specific redirect.

HTTP Request

PUT {base_url}/redirects/:id

URL Parameters

Parameter Description
:post_id The id of the post to which the updated redirect belongs
:id The id of the redirect to update

PUT Parameters

Parameter Description Constraints
from_url The new path which is redirected Is a valid http path.

Alternative endpoints

Alternative endpoints are:

Delete redirect

DELETE {base_url}/posts/1/redirects/1 returns JSON structured like this:

{
  "data": {
    "id": 1,
    "type": "redirects",
    "attributes": {
      "from_url": "/a/new/path"
    },
    "relations": {
      "post_id": 1
    }
  }
}

This endpoint deletes a specific redirect.

HTTP Request

DELETE {base_url}/redirects/:id

URL Parameters

Parameter Description
:post_id The id of the post to which the delete redirect belongs
:id The id of the redirect to delete

Alternative endpoints

Alternative endpoints are:

Site Translations

Get all site translations

GET {base_url}/sites/1/site_translations/ returns JSON structured like this:

{
  "data": [
    {
      "id": 3,
      "type": "site_translations",
      "attributes" : {
        "language": "nl",
        "content": {
          "content_field_1": {
            "value": [1032, 12, 1],
            "type": "reference",
            "subtype": "element",
            "content_field_id": 82
          },
          "content_field_2": {
            "value": "Go girl",
            "type": "text",
            "content_field_id": 83
          }
        }
      },
      "relations" : {
        "site_id": 1,
        "content_type_id": 16
      }
    },
    {
      "id": 2,
      "type": "site_translations",
      "attributes" : {
        "language": "en",
        "content": {
          "content_field_1": {
            "value": [1032, 123, 456],
            "type": "reference",
            "subtype": "element",
            "content_field_id": 82
          },
          "content_field_2": {
            "value": "A little text",
            "type": "text",
            "content_field_id": 83
          }
        }
      },
      "relations" : {
        "site_id": 1,
        "content_type_id": 16
      }
    }
  ]
}

This endpoint retrieves all site translations for a specific site

HTTP Request

GET {base_url}/sites/:site_id/site_translations

URL Parameters

Parameter Description
:site_id The id of the site to which the site_translations belong

Get specific site translations

GET {base_url}/sites/1/site_translations/3 returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "site_translations",
    "attributes" : {
      "language": "nl",
      "content": {
        "content_field_1": {
          "value": [1032, 12, 1],
          "type": "reference",
          "subtype": "element",
          "content_field_id": 82
        },
        "content_field_2": {
          "value": "Go girl",
          "type": "text",
          "content_field_id": 83
        }
      }
    },
    "relations" : {
      "site_id": 1,
      "content_type_id": 16
    }
  }
}

This endpoint retrieves a specific site translation.

HTTP Request

GET {base_url}/site_translations/:id

URL Parameters

Parameter Description
:site_id The id of the site of the site translation to retrieve
:id The id of the site translation to retrieve

Alternative endpoints

Alternative endpoints are:

Update site translation

An example of valid JSON PUT parameters

{
  "data": {    
    "content_field_1": [
      {
        "id": 22,
      },
      {
        "id": 24,
        "reference_content_field_1": "Updated text for existing content_reference"
      },
      {
        "reference_content_field_1": "I am a referenced element",
        "reference_content_field_2": "Some text",

      }
    ],
    "content_field_2": "New text"
  }
}

PUT {base_url}/sites/1/site_translations/3 with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "site_translations",
    "attributes" : {
      "language": "nl",
      "content": {
        "content_field_1": {
          "value": [22, 23, 1033],
          "type": "reference",
          "subtype": "element",
          "content_field_id": 82
        },
        "content_field_2": {
          "value": "New text",
          "type": "text",
          "content_field_id": 83
        }
      }
    },
    "relations" : {
      "site_id": 1,
      "content_type_id": 16
    }
  }
}

This endpoint updates a site translation.

HTTP Request

PUT {base_url}/site_translations/:id

URL Parameters

Parameter Description
:site_id The id of the site of the site translation to retrieve
:id The id of the site translation to retrieve

PUT Parameters

Parameter Description Constraints
--Accepts Content field parameters--

Alternative endpoints

Alternative endpoints are:

Posts

Get all posts

GET {base_url}/site_translations/1/posts/ returns JSON structured like this:

{
  "data": [
    {
      "id": 3,
      "type": "posts",
      "attributes" : {
        "title": "A Post title",
        "language": "nl",
        "content": {
          ...
        }
      },
      "relations" : {
        "site_translation_id": 1,
        "content_type_id": 14
      }
    },
    {
      "id": 4,
      "type": "posts",
      "attributes" : {
        "title": "Another Post title",
        "language": "nl",
        "content": {
          ...
        }
      },
      "relations" : {
        "site_translation_id": 1,
        "content_type_id": 14
      }
    },
  ]
}

This endpoint retrieves all posts for a specific site translation

HTTP Request

GET {base_url}/site_translations/:site_translation_id/posts

URL Parameters

Parameter Description
:site_translation_id The id of the site translation to which the posts belong
:site_id The id of the site to which the posts belong

Alternative endpoints

Alternative endpoints are:

Get specific post

GET {base_url}/site_translations/1/posts/3 returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "posts",
    "attributes" : {
      "title": "A Post title",
      "language": "nl",
      "content": {
        ...
      }
    },
    "relations" : {
      "site_translation_id": 1,
      "content_type_id": 14
    }
  }
}

This endpoint retrieves a specific post.

HTTP Request

GET {base_url}/posts/:id

URL Parameters

Parameter Description
:site_translation_id The id of the site translation of the post to retrieve
:id The id of the post to retrieve
:site_id The id of the site of the post to retrieve

Alternative endpoints

Alternative endpoints are:

Create post

An example of valid JSON POST parameters

{
  "data": {    
    "content_type_id": 14,
    "title": "Created Post",
  }
}

POST {base_url}/site_translations/1/posts with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 5,
    "type": "posts",
    "attributes" : {
      "title": "Created Post",
      "language": "nl",
      "content": {
        ...
      }
    },
    "relations" : {
      "site_translation_id": 1,
      "content_type_id": 14
    }
  }
}

This endpoint creates a post.

HTTP Request

POST {base_url}/site_translations/:site_translation_id/posts

URL Parameters

Parameter Description
:site_translation_id The id of the site translation to which the new post belongs

POST Parameters

Parameter Description Constraints
content_type_id The content type of the new post Required
title The title of the new post Required
language The language of the new post Required. Has to be one of the languages of the site of the new post.
seo_title The SEO title of the new post
seo_description The SEO description of the new post
--Accepts Content field parameters--

Update post

An example of valid JSON PUT parameters

{
  "data": {    
    "title": "An updated post title",
  }
}

PUT {base_url}/site_translations/1/posts/3 with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "posts",
    "attributes" : {
      "title": "An updated post title",
      "language": "nl",
      "content": {
        ...
      }
    },
    "relations" : {
      "site_translation_id": 1,
      "content_type_id": 14
    }
  }
}

This endpoint updates a post.

HTTP Request

PUT {base_url}/posts/:id

URL Parameters

Parameter Description
:site_translation_id The id of the site translation of the post to update
:id The id of the post to update
:site_id The id of the site of the post to update

PUT Parameters

Parameter Description Constraints
title The title of the post Not null
--Accepts Content field parameters--

Alternative endpoints

Alternative endpoints are:

Delete post

DELETE {base_url}/site_translations/1/posts/3 returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "posts",
    "attributes" : {
      "title": "A Post title",
      "language": "nl",
      "content": {
        ...
      }
    },
    "relations" : {
      "site_translation_id": 1,
      "content_type_id": 14
    }
  }
}

This endpoint deletes a specific post.

HTTP Request

DELETE {base_url}/posts/:id

URL Parameters

Parameter Description
:site_translation_id The id of the site translation of the post to delete
:id The id of the post to delete
:site_id The id of the site of the post to delete

Alternative endpoints

Alternative endpoints are:

Sections

Get all sections

GET {base_url}/posts/1/sections/ returns JSON structured like this:

{
  "data": [
    {
      "id": 3,
      "type": "sections",
      "attributes" : {
        "position": 1,
        "name": "A Section name",
        "content": {
          ...
        }
      },
      "relations" : {
        "post_id": 1,
        "content_type_id": 14
      }
    },
    {
      "id": 4,
      "type": "sections",
      "attributes" : {
        "position": 2,
        "name": "Another Section name",
        "content": {
          ...
        }
      },
      "relations" : {
        "post_id": 1,
        "content_type_id": 14
      }
    }
  ]
}

This endpoint retrieves all sections for a specific post

HTTP Request

GET {base_url}/posts/:post_id/sections

URL Parameters

Parameter Description
:post_id The id of the posts to which the sections belong
:site_id The id of the site to which the sections belong
:site_translation_id The id of the site translation to which the sections belong

Alternative endpoints

Alternative endpoints are:

Get specific section

GET {base_url}/posts/1/sections/3 returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "sections",
    "attributes" : {
      "position": 1,
      "name": "A Section name",
      "content": {
        ...
      }
    },
    "relations" : {
      "post_id": 1,
      "content_type_id": 14
    }
  }
}

This endpoint retrieves a specific section.

HTTP Request

GET {base_url}/sections/:id

URL Parameters

Parameter Description
:post_id The id of the posts of the section to retrieve
:id The id of the section to retrieve
:site_id The id of the site of the section to retrieve
:site_translation_id The id of the site of site_translation the section to retrieve

Alternative endpoints

Alternative endpoints are:

Create section

An example of valid JSON POST parameters

{
  "data": {    
    "content_type_id": 14,
    "name": "Created Section",
    "position": 1
  }
}

POST {base_url}/posts/1/sections with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 4,
    "type": "sections",
    "attributes" : {
      "position": 1,
      "name": "Created Section",
      "content": {
        ...
      }
    },
    "relations" : {
      "post_id": 1,
      "content_type_id": 14
    }
  }
}

This endpoint creates a section in a post.

HTTP Request

POST {base_url}/posts/:post_id/sections

URL Parameters

Parameter Description
:post_id The id of the posts to which the new section belongs

POST Parameters

Parameter Description Constraints
content_type_id The content type of the new section Required
name The name of the new section Required
--Accepts the position field for positionable objects--
--Accepts Content field parameters--

Update section

An example of valid JSON PUT parameters

{
  "data": {    
    "name": "Updated Section Name",
    "position": 3
  }
}

PUT {base_url}/posts/1/sections/4 with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 4,
    "type": "sections",
    "attributes" : {
      "position": 3,
      "name": "Updated Section Name",
      "content": {
        ...
      }
    },
    "relations" : {
      "post_id": 1,
      "content_type_id": 14
    }
  }
}

This endpoint updates a section.

HTTP Request

PUT {base_url}/sections/:id

URL Parameters

Parameter Description
:post_id The id of the posts of the section to update
:id The id of the section to update
:site_id The id of the site of the section to update
:site_translation_id The id of the site translation of the section to update

PUT Parameters

Parameter Description Constraints
name The new name of the section Not null
--Accepts the position field for positionable objects--
--Accepts Content field parameters--

Alternative endpoints

Alternative endpoints are:

Delete section

DELETE {base_url}/posts/1/sections/4 returns JSON structured like this:

{
  "data": {
    "id": 4,
    "type": "sections",
    "attributes" : {
      "position": 3,
      "name": "Updated Section Name",
      "content": {
        ...
      }
    },
    "relations" : {
      "post_id": 1,
      "content_type_id": 14
    }
  }
}

This endpoint deletes a specific section.

HTTP Request

DELETE {base_url}/sections/:id

URL Parameters

Parameter Description
:post_id The id of the posts of the section to delete
:id The id of the section to delete
:site_id The id of the site of the section to delete
:site_translation_id The id of the site_translation of the section to delete

Alternative endpoints

Alternative endpoints are:

Rows

Get all rows

GET {base_url}/sections/1/rows/ returns JSON structured like this:

{
  "data": [
    {
      "id": 3,
      "type": "rows",
      "attributes" : {
        "position": 1
      },
      "relations" : {
        "section_id": 1
      }
    },
    {
      "id": 4,
      "type": "rows",
      "attributes" : {
        "position": 2
      },
      "relations" : {
        "section_id": 1
      }
    }
  ]
}

This endpoint retrieves all rows for a specific section

HTTP Request

GET {base_url}/sections/:section_id/rows

URL Parameters

Parameter Description
:section_id The id of the sections to which the rows belong
:site_id The id of the site to which the rows belong
:site_translation_id The id of the site translation to which the rows belong
:post_id The id of the post to which the rows belong

Alternative endpoints

Alternative endpoints are:

Get specific row

GET {base_url}/sections/1/rows/3 returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "rows",
    "attributes" : {
      "position": 1
    },
    "relations" : {
      "section_id": 1
    }
  }
}

This endpoint retrieves a specific row.

HTTP Request

GET {base_url}/rows/:id

URL Parameters

Parameter Description
:section_id The id of the sections of the row to retrieve
:id The id of the row to retrieve
:site_id The id of the site of the row to retrieve
:site_translation_id The id of the site of site_translation the row to retrieve
:post_id The id of the post of the row to retrieve

Alternative endpoints

Alternative endpoints are:

Create row

An example of valid JSON POST parameters

{
  "data": {    
    "position": 1
  }
}

POST {base_url}/sections/1/rows with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 5,
    "type": "rows",
    "attributes" : {
      "position": 1
    },
    "relations" : {
      "section_id": 1
    }
  }
}

This endpoint creates a row in a section.

HTTP Request

POST {base_url}/sections/:section_id/rows

URL Parameters

Parameter Description
:section_id The id of the sections to which the new row belongs

POST Parameters

Parameter Description Constraints
--Accepts the position field for positionable objects--

Update row

An example of valid JSON PUT parameters

{
  "data": {    
    "position": 3
  }
}

PUT {base_url}/sections/1/rows/4 with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 5,
    "type": "rows",
    "attributes" : {
      "position": 3
    },
    "relations" : {
      "section_id": 1
    }
  }
}

This endpoint updates a row.

HTTP Request

PUT {base_url}/rows/:id

URL Parameters

Parameter Description
:section_id The id of the sections of the row to update
:id The id of the row to update
:site_id The id of the site of the row to update
:site_translation_id The id of the site translation of the row to update
:post_id The id of the post of the row to update

PUT Parameters

Parameter Description Constraints
--Accepts the position field for positionable objects--

Alternative endpoints

Alternative endpoints are:

Delete row

DELETE {base_url}/sections/1/rows/4 returns JSON structured like this:

{
  "data": {
    "id": 4,
    "type": "rows",
    "attributes" : {
      "position": 3
    },
    "relations" : {
      "section_id": 1
    }
  }
}

This endpoint deletes a specific row.

HTTP Request

DELETE {base_url}/rows/:id

URL Parameters

Parameter Description
:section_id The id of the sections of the row to delete
:id The id of the row to delete
:site_id The id of the site of the row to delete
:site_translation_id The id of the site_translation of the row to delete
:post_id The id of the site of the row to delete

Alternative endpoints

Alternative endpoints are:

Columns

Get all columns

GET {base_url}/rows/1/columns/ returns JSON structured like this:

{
  "data": [
    {
      "id": 3,
      "type": "columns",
      "attributes" : {
        "position": 1
      },
      "relations" : {
        "row_id": 1
      }
    },
    {
      "id": 4,
      "type": "columns",
      "attributes" : {
        "position": 2
      },
      "relations" : {
        "row_id": 1
      }
    }
  ]
}

This endpoint retrieves all columns for a specific row

HTTP Request

GET {base_url}/rows/:row_id/columns

URL Parameters

Parameter Description
:row_id The id of the rows to which the columns belong
:site_id The id of the site to which the columns belong
:site_translation_id The id of the site translation to which the columns belong
:post_id The id of the post to which the columns belong
:section_id The id of the section to which the columns belong

Alternative endpoints

Alternative endpoints are:

Get specific column

GET {base_url}/rows/1/columns/3 returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "columns",
    "attributes" : {
      "position": 1
    },
    "relations" : {
      "row_id": 1
    }
  }
}

This endpoint retrieves a specific column.

HTTP Request

GET {base_url}/columns/:id

URL Parameters

Parameter Description
:row_id The id of the rows of the column to retrieve
:id The id of the column to retrieve
:site_id The id of the site of the column to retrieve
:site_translation_id The id of the site of site_translation the column to retrieve
:post_id The id of the post of the column to retrieve
:section_id The id of the section of the column to update

Alternative endpoints

Alternative endpoints are:

Create column

An example of valid JSON POST parameters

{
  "data": {    
    "position": 1
  }
}

POST {base_url}/rows/1/columns with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 5,
    "type": "columns",
    "attributes" : {
      "position": 1
    },
    "relations" : {
      "row_id": 1
    }
  }
}

This endpoint creates a column in a row.

HTTP Request

POST {base_url}/rows/:row_id/columns

URL Parameters

Parameter Description
:row_id The id of the rows to which the new column belongs

POST Parameters

Parameter Description Constraints
--Accepts the position field for positionable objects--

Update column

An example of valid JSON PUT parameters

{
  "data": {    
    "position": 3
  }
}

PUT {base_url}/rows/1/columns/4 with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 5,
    "type": "columns",
    "attributes" : {
      "position": 3
    },
    "relations" : {
      "row_id": 1
    }
  }
}

This endpoint updates a column.

HTTP Request

PUT {base_url}/columns/:id

URL Parameters

Parameter Description
:row_id The id of the row of the columns to update
:id The id of the column to update
:site_id The id of the site of the column to update
:site_translation_id The id of the site translation of the column to update
:post_id The id of the post of the column to update
:section_id The id of the section of the column to update

PUT Parameters

Parameter Description Constraints
--Accepts the position field for positionable objects--

Alternative endpoints

Alternative endpoints are:

Update column grid

An example of valid JSON PUT parameters

{
  "data": [
    {
      "id": 1,
      "grid": 9
    },
    {
      "id": 2,
      "grid": 3
    }
  ]
}

PUT {base_url}/rows/1/columns/ with the above parameters returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "type": "columns",
      "attributes" : {
        "position": 1
      },
      "relations" : {
        "row_id": 1
      }
    },
    {
      "id": 4,
      "type": "columns",
      "attributes" : {
        "position": 2
      },
      "relations" : {
        "row_id": 1
      }
    }
  ]
}

This endpoint updates the grid of columns in a row. It requires an array with objects containing the id of a column, and the (new) non-zero grid of that column. The sum of all the specified grids has to be 12, and all column ids should be present.

HTTP Request

PUT {base_url}/rows/:row_id/columns/

URL Parameters

Parameter Description
:row_id The id of the row of the columns to update

PUT Parameters

Parameter Description Constraints
id The id of a column
grid The grid of a column At least 1. Not null. The grids should sum up to 12.

Delete column

DELETE {base_url}/rows/1/columns/4 returns JSON structured like this:

{
  "data": {
    "id": 4,
    "type": "columns",
    "attributes" : {
      "position": 3
    },
    "relations" : {
      "row_id": 1
    }
  }
}

This endpoint deletes a specific column.

HTTP Request

DELETE {base_url}/columns/:id

URL Parameters

Parameter Description
:row_id The id of the rows of the column to delete
:id The id of the column to delete
:site_id The id of the site of the column to delete
:site_translation_id The id of the site_translation of the column to delete
:post_id The id of the site of the column to delete
:section_id The id of the section of the column to update

Alternative endpoints

Alternative endpoints are:

Elements

Get all elements

GET {base_url}/columns/1/elements/ returns JSON structured like this:

{
  "data": [
    {
      "id": 3,
      "type": "elements",
      "attributes" : {
        "position": 1,
        "content": {
          ...
        }
      },
      "relations" : {
        "column_id": 1,
        "content_type_id": 14
      }
    },
    {
      "id": 4,
      "type": "elements",
      "attributes" : {
        "position": 2,
        "name": "Another Element name",
          ...
        }
      },
      "relations" : {
        "column_id": 1,
        "content_type_id": 14
      }
    }
  ]
}

This endpoint retrieves all elements for a specific column

HTTP Request

GET {base_url}/columns/:column_id/elements

URL Parameters

Parameter Description
:column_id The id of the columns to which the elements belong
:site_id The id of the site to which the elements belong
:site_translation_id The id of the site translation to which the elements belong
:post_id The id of the posts to which the elements belong
:section_id The id of the sections to which the elements belong
:row_id The id of the rows to which the elements belong

Alternative endpoints

Alternative endpoints are:

Get specific element

GET {base_url}/columns/1/elements/3 returns JSON structured like this:

{
  "data": {
    "id": 3,
    "type": "elements",
    "attributes" : {
      "position": 1,
      "content": {
        ...
      }
    },
    "relations" : {
      "column_id": 1,
      "content_type_id": 14
    }
  }
}

This endpoint retrieves a specific element.

HTTP Request

GET {base_url}/elements/:id

URL Parameters

Parameter Description
:id The id of the element to retrieve

Alternative endpoints

Alternative endpoints are:

Create element

An example of valid JSON POST parameters

{
  "data": {    
    "content_type_id": 14,
    "position": 1
  }
}

POST {base_url}/columns/1/elements with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 4,
    "type": "elements",
    "attributes" : {
      "position": 1,
      "content": {
        ...
      }
    },
    "relations" : {
      "column_id": 1,
      "content_type_id": 14
    }
  }
}

This endpoint creates an element in a column.

HTTP Request

POST {base_url}/columns/:column_id/elements

URL Parameters

Parameter Description
:column_id The id of the columns to which the new element belongs

POST Parameters

Parameter Description Constraints
content_type_id The content type of the new element Required
--Accepts the position field for positionable objects--
--Accepts Content object parameters--

Update element

An example of valid JSON PUT parameters

{
  "data": {    
    "position": 3
  }
}

PUT {base_url}/columns/1/elements/4 with the above parameters returns JSON structured like this:

{
  "data": {
    "id": 4,
    "type": "elements",
    "attributes" : {
      "position": 3,
      "content": {
        ...
      }
    },
    "relations" : {
      "column_id": 1,
      "content_type_id": 14
    }
  }
}

This endpoint updates an element.

HTTP Request

PUT {base_url}/elements/:id

URL Parameters

Parameter Description
:id The id of the element to update

PUT Parameters

Parameter Description Constraints
--Accepts the position field for positionable objects--
--Accepts Content field parameters--

Alternative endpoints

Alternative endpoints are:

Delete element

DELETE {base_url}/columns/1/elements/4 returns JSON structured like this:

{
  "data": {
    "id": 4,
    "type": "elements",
    "attributes" : {
      "position": 3,
      "content": {
        ...
      }
    },
    "relations" : {
      "column_id": 1,
      "content_type_id": 14
    }
  }
}

This endpoint deletes a specific element.

HTTP Request

DELETE {base_url}/elements/:id

URL Parameters

Parameter Description
:id The id of the element to delete

Alternative endpoints

Alternative endpoints are: