REST Management API

The REST Management API provides for the ability to manage your data in your Brightspot CMS instance over HTTP, via CRUD operations over a standard JSON REST API implementation.

As with any typical CRUD API, the operations are mapped to HTTP methods — POST, GET, PUT, DELETE.

Authentication

Accessing the API endpoints requires passing valid X-Client-Id and X-Client-Secret HTTP headers. Your Brightspot administrator should provide those values to you.

Content querying

The endpoint for accessing instances of your content types data (e.g., articles) is available by default at /api/rest/cma/contents. Note that your Brightspot administrator may have customized this, in which case the path may be different.

With a GET request, you can query for results of a given content type using the from parameter, where the passed value corresponds to the fully qualified type name. For example: /api/rest/cma/contents?from=com.psddev.cms.db.Text

You can further refine the query with the following parameters:

Parameter	Description	Example
where	Query predicate string. If `?` placeholder(s) are included, values parameter(s) need to be passed corresponding to each placeholder.	where="cms.content.publishDate > 1666367884043" where="name = ?"
offset	Pagination offset number	offset=20
limit	Pagination limit number	limit=10
values	Values for `?` placeholders in query predicate	values="My great content"

Examples using curl:

# simple from
curl -X GET 'http://localhost/api/rest/cma/contents?from=com.psddev.cms.db.Text' \
-H 'X-Client-Id: {{client ID}}' \ 
-H 'X-Client-Secret: {{client secret}}'

# pagination
curl -X GET 'http://localhost/api/rest/cma/contents?from=com.psddev.cms.db.Text&offset=20&limit=10' \
-H 'X-Client-Id: {{client ID}}' \
-H 'X-Client-Secret: {{client secret}}'

# where="name = ?",  values="My Content"
curl -X GET 'http://localhost/api/rest/cma/contents?from=com.psddev.cms.db.Text&where=name%20%3D%20?&values=My%20Content' \
-H 'X-Client-Id: {{client ID}}' \
-H 'X-Client-Secret: {{client secret}}'

Content management

The /api/rest/cma/contents endpoint is also used for creating new or managing existing pieces of content.

Create (POST)

Issuing a POST request with a JSON body to this API results in new content being created. For example, the following CURL command saves a new instance of Raw HTML (com.psddev.cms.db.Text) in Brightspot, owned by a given site.

curl -X POST 'http://localhost/api/rest/cma/contents' \
-H 'Content-Type: application/json' \
-H 'X-Client-Id: {{client ID}}' \ 
-H 'X-Client-Secret: {{client secret}}' \
--data-raw '{
    "_type": "com.psddev.cms.db.Text",
    "name": "My New HTML Content",
    "text": "<b>Hello Raw HTML!</b>",
    "cms.site.owner": {
        "_ref": {{Site ID}},
        "_type": {{Site type ID}}"
    }    
}'

Update (PUT)

Issuing a PUT request with a JSON body to this API results in existing content being updated. In this case, the content ID must be appended to the endpoint path, as such: /api/rest/cma/contents/{{UUID string}}. In the following example, the content instance created in the previous example is updated, changing the text field.

curl -X PUT 'http://localhost/api/rest/cma/contents/00000183-fbf4-d9c6-a5f7-fbfc10db0000' \
-H 'Content-Type: application/json' \
-H 'X-Client-Id: {{client ID}}' \ 
-H 'X-Client-Secret: {{client secret}}' \
--data-raw '{
    "text": "<b>Hello UPDATED Raw HTML!</b>"
}'

Read (GET)

To fetch/read the data for a given content ID, issue a GET request:

curl -X GET 'http://localhost/api/rest/cma/contents/00000183-fbf4-d9c6-a5f7-fbfc10db0000' \
-H 'Content-Type: application/json' \
-H 'X-Client-Id: {{client ID}}' \ 
-H 'X-Client-Secret: {{client secret}}'

Delete (DELETE)

Issuing a DELETE request to this API for the given content ID results in the content being removed from Brightspot.

curl -X DELETE 'http://localhost/api/rest/cma/contents/00000183-fbf4-d9c6-a5f7-fbfc10db0000' \
-H 'Content-Type: application/json' \
-H 'X-Client-Id: {{client ID}}' \ 
-H 'X-Client-Secret: {{client secret}}'