JSON API

Introduction

The JSON API allows Mura CMS to be the main content creation hub within an organization, and allows developers to build their front-ends as pure JavaScript clients.

How To Enable

This feature may be enabled on a per site basis. From the back end administration area, go to Site Config > Edit Site. Then, select the Modules tab. From there, locate the JSON API, and select either Off or On. Then click Update.

Base URL

The base URL for the API endpoints is:

https://yourDomain.com/{context}/index.cfm/_api/json/v1/

API Endpoint Reference

Method	Endpoint	Usage	Returns
GET	/{siteid}/{entityname}/{id}	FindOne	data
GET	/{siteid}/entityname}/{ids}	FindMany	data
GET	/{siteid}/{entityname}/new	FindNew	data
GET	/{siteid}/{entityname}/?	FindQuery	data
GET	/{siteid}/{entityname}/{id}/{releatedentity}/?	FindRelatedEntity	data
GET,POST	/?method=findCalenderItems&siteid={siteid}&calendarid={calendarid}&start={start}&end={end}&format={format}	FindCalendarItems	data | events
POST	/?method=generateCSRFTokens&siteid={siteid}&context={entityid}	GenerateCSRFTokens	data
POST	/{siteid}/{entityname}/?csrf_token={csrf_token}&csrf_token_expires={csrf_token_expires}	Save	data
DELETE	/{siteid}/{entityname}/{id}/?csrf_token={csrf_token}&csrf_token_expires={csrf_token_expires}	Delete	data
GET,POST	/{siteid}/login/?username={username}&password={password}	Login	data
GET,POST	/{siteid}/logout	Logout	data

Response Format

On success, the HTTP status code in the response header is 200 OK and the response body contains a data object in JSON format. On error, the header status code is an error code and the response body contains an error object.

Example Response

{
"data": {
"key": "value"
}
}

Response Status Codes

The JSON API uses the following response status codes:

Status Code	Description
200	OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.
400	Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information; see Error Handling, below.
401	Unauthorized - The request requires user authentication or, if the request included authoriation credentials, authorization has been refused for those credentials. Also, the JSON API feature may not be enabled for the site; see How To Enable, above.
403	Forbidden - The server understood the request, but is refusing to fulfill it. For example, requestor does not have permission to a requested method.
404	Not Found - The requested resource could not be found. This error can be due to a temporary or permanent condition.

Error Handling

When an error occurs, the response data attribute will not exist. The response will instead contan an error attribute.

Example Error Response

{
"error": {
"message": "Insufficient Account Permissions"
}
}

Example Response Handler

$.getJSON('/index.cfm/json/v1/default/content/').then(
function( resp ) {
if ( 'error' in resp ) {
//handle error
} else {
//do stuff
}
}
});

History

Feature added in version 6.2.