REST API
The BranchCMS REST API enables developers to easily interact with your website via third-party applications or external data sources. Requests are made to the API using standard GET, POST, PUT, PATCH and DELETE commands and the API returns its results in JSON.
This is different from the internal data API that can be used to display content from one area of the website in another area.
Authentication
In order to access the API, you will need to provide an access token to authenticate with the API server. That token will be required for all API requests.
Authentication is done by passing a valid API token using the Authorization header.
Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9
The value for the "Authorization" header starts with Bearer followed by a space and then followed by the API token.
It is strongly recommended that you use https for all API requests to protect the authentication.
It is your responsibility to protect the API authentication.
You can generate an API token by going to Settings -> API in the administration.
Accept header required
All requests must include the "Accept" header. The only allowed value is "application/json".
curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/account/accounts?limit=2'
User-Agent header required
All requests must include the User-Agent header.
Some tools such as Insomnia or curl on the command line will include a default User Agent. Other environments, like curl with PHP, do not set a default user agent. You would need to do this yourself.
Any valid user agent value can be used.
<?php
$url = "https://www.mysite.com/api/v1/account/accounts?limit=2";
$authToken = "MYAPIAUTHORIZATIONTOKEN";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("User-Agent: MyCustomUserAgent","Accept: application/json", "Content-Type: application/json", "Authorization: Bearer $authToken"));
$result = curl_exec($ch);
curl_close($ch)
Base URL
The base URL for all requests is /api/v1/.
HTTP verbs
Where possible the API strives to use appropriate HTTP verbs for each action.
| Verb | Description |
|---|---|
| GET | Used for retrieving a list of items or a single item. |
| POST | Used for creating items (e.g. adding a new calendar event). The POST request is also used for uploading an image or file. |
| PATCH | Used for partially updating an item. A PATCH request will accept one or more valid attributes for an item to update and only the passed attributes will be updated. |
| PUT | Used for replacing an item. This would completely edit the item. It's expected that all valid attributes are passed. If an attribute is left out then it's current value will be cleared when the item is saved. |
| DELETE | Used for deleting items. |
Parameters
Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter.
For example, when getting a list of events you can specify how many to return.
curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/calendar/events?page=1&limit=5'
Default limit
If the limit parameter is not specified then the result will default to 20 items per set.
Common parameters
The following are some common parameters that you may use when making API requests.
Responses
All API responses will be in JSON and HTTP status codes are used to indicate the type of response.
The contents of the response will depend on what type of request you made.
Getting a list of items
curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/account/accounts?sort=+lastName&limit=5'
{
data: [
{
...item data here...
},
{
...item data here...
},
],
"pagination": {
"currentPage": 1,
"perPage": 6,
"count": 6,
"totalPages": 312,
"total": 1867,
"links": {
"next": "?page=2&limit=6&sort=-lastName"
}
},
"totalItems": 1867
}
Retrieve a single item
curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/calendar/events/94'
{
"id": 132
"title": "Event Title",
....more app item data here....
}
Adding an item
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' -d '{...item data here...}' 'http://www.mysite.com/api/v1/calendar/events'
If the item was successfully created then a 201 HTTP status code is returned.
The data for the item that was just added is returned. Same as the response for retrieving a single item.
{
"id": 132
"title": "Event Title",
....more app item data here....
}
Editing an item
curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' -d '{...item data here...}' 'http://www.mysite.com/api/v1/calendar/events/10'
If the item was successfully edited then a 200 HTTP status code is returned.
The data for the item that was just edited is returned. Same as the response for retrieving a single item.
{
"id": 132
"title": "Event Title",
....more app item data here....
}
Deleting an item
curl -X DELETE --H 'Accept: application/json' --H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/calendar/events/1784'
No response is returned if the deletion is successful. A HTTP status code of 204 is returned.
Partially editing an item
curl -X PATCH -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' -d '{...item data here...}' 'http://www.mysite.com/api/v1/calendar/events/10'
If the item was successfully edited then a 200 HTTP status code is returned.
The data for the item that was just edited is returned. Same response a retrieving a single item.
{
"id": 132
"title": "Event Title",
....more app item data here....
}
Uploading a file or image to an app item
curl -X POST -H 'Content-Type: multipart/form-data' -H 'Accept: text/html' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' {"type":"formData"} 'http://devhosted.aptuitiv.com/api/v1/calendar/upload?attribute=image'
Below is an example response from successfully uploading an image.
{
"src": "/images/myimage.jpg",
"fileName": "myimage.jpg",
"fileExtension": "jpg",
"type": "image",
"typeName": "JPG Image",
"alt": "",
"height": "200",
"width": "300"
}
Below is an example response from successfully uploading a PDF.
{
"src": "/docs/myfile.pdf",
"fileName": "myfile.pdf",
"fileExtension": "pdf",
"type": "pdf",
"typeName": "PDF"
}
Errors
If there is an error in the request then the appropriate HTTP status code will be returned with the response headers. The response content will contain JSON similar to the following.
{
"errors": [
{
"code": 401,
"title": "Unauthorized",
"detail": "API Key is not Valid"
}
]
}
HTTP status codes
Successful API requests will have a 200 HTTP status code.
If there was an error, then a 4xx status code or a 500 status code will be returned.
Below is a list of status codes that could be returned.
| Response Codes | Description |
|---|---|
| 200 | OK The request was successful and a valid response is returned. |
| 201 | Created The item was successfully created. This is returned when adding a new app item and it was successfully added. |
| 204 | No Content The request was successfully processed but no content is returned. This is the response code if an app item is successfully deleted. |
| 400 | Bad Request The request could not be processed due to an issue with how the request was made. Possible reasons for the error include:
|
| 401 | Unauthorized The request could not be authenticated. Either the API authentication key is missing or it's invalid. |
| 404 | Not Found Possible reasons for the error include:
|
| 415 | Unsupported Media Type Possible reasons for the error include:
|
| 422 | Unprocessable Entity Possible reasons for the error include:
|
Pagination
Requests that return multiple items will be paginated to 20 items by default. You can specify further pages with the page parameter. You can adjust the number of items returned by passing the limit parameter.
For example, getting the list of accounts without passing the page or limit parameters will return 20 results.
curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/account/accounts'
The response will also include pagination data and the total number of items that could be returned.
{
data: [
{
...item data here...
},
{
...item data here...
},
],
"pagination": {
"currentPage": 1,
"perPage": 20,
"count": 20,
"totalPages": 94,
"total": 1867,
"links": {
"next": "?page=2&limit=6&sort=-lastName"
}
},
"totalItems": 1867
}
In the pagination data is a links object. This will contain the links to go to the previous or next page.
For example, if you passed the page parameter the pagination link data would include the previous and next URLs to retrieve the previous or next set of data.
curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/account/accounts?page=3'
{
data: [
{
...item data here...
},
{
...item data here...
},
],
"pagination": {
"currentPage": 3,
"perPage": 20,
"count": 20,
"totalPages": 94,
"total": 1867,
"links": {
"previous": "?page=2&limit=20",
"next": "?page=2&limit=6&sort=-lastName"
}
},
"totalItems": 1867
}