Describes the available REST APIs to Optimizely CMS SaaS Core.
Beta
Optimizely SaaS Core is in beta. Apply on Join the waitlist for SaaS Core or contact your Customer Success Manager.
Optimizely Content Management System (CMS) SaaS Core has multiple REST APIs to manage resources in your AWS instance. This topic describes the functionality of the available REST APIs and what endpoints are available for SaaS Core.
You can download the OpenAPI schema for these APIs from https://example.com/_cms/{version}/docs/content-openapi.json
. Replace {version}
with your version number. For example:
- If you have a site on CMS PaaS with the API installed:
https://example.com/_cms/preview1/docs/content-openapi.json
- If you are trying the current CMS SaaS Core beta program
https://example.com/_cms/v0.5/docs/content-openapi.json
- When the CMS SaaS Core API is released to general availability (GA).
https://example.com/_cms/v1/docs/content-openapi.json
Management and delivery
REST APIs are intended for managing resources. Every SaaS Core instance has an Optimizely Graph instance for high-performance delivery purposes.
Authentication
See authentication and authorization.
API Requests
Requests and responses use Content-Type: application/json
unless otherwise specified. Unknown fields in requests are ignored unless otherwise stated. Any invalid field type will result in an error response.
Responses may include additional fields not defined in the specification. The client should be able to handle this. Operations that normally return a 200 OK
response may return 202 Accepted
in the future, if the service believes the operation will take too long to process. Such a response includes information about where the operation processing status can be retrieved.
GET requests
GET
requests are used to retrieve existing resources. Generally, when a request is without a resource key, a list of resources matching the request is returned.
Paging
Most listing endpoints take query parameters pageIndex
and pageSize
.
- The
pageIndex
argument is a zero-based index that decides which page of resources to return. If omitted, the first page are returned. - The
pageSize
argument defines how many items are returned, at most. If omitted, each page includes up to 100 resources unless defined otherwise.
The listing response returns a resource list in the following format, where the resources are included under the items
field.
{
"items": [],
"pageSize": 10,
"pageIndex": 2,
"totalItemCount": 421
}
The service will omit the pageSize
and pageIndex
fields if all existing resources were returned. The totalItemCount
field provides an approximate indication of the total number of items available; it will not be returned if the total number of resources is unknown.
POST requests
POST
requests are mostly used to create resources but are sometimes used for custom actions. In such cases, the resource path ends with a suffix representing the action. For example, the :copy
suffix is used for the endpoint that creates a copy of an existing content item.
PUT requests
Use a PUT
request to create a resource or replace an existing resource. Not all resource types supports PUT
requests.
To prevent a new resource from being created if the resource does not exist, include the If-Match=*
header with the request.
To ensure that no one has updated an existing resource since you last checked, pass in the ETag
returned in the response header from a GET
request for the same resource in the If-Match
request header.
PATCH requests
Use a PATCH
request to update existing resources. The CMS API follows the JSON Merge Patch standard and expects a Content-Type: application/merge-patch+json
header with requests.
To ensure that no one has updated an existing resource since you last checked, pass in the ETag
returned in the response header from a GET
request for the same resource in the If-Match
request header.
DELETE requests
Use a DELETE
request to delete existing resources.
To ensure that no one has updated an existing resource since you last checked, pass in the ETag
returned in the response header from a GET
request for the same resource in the If-Match
request header.
Error responses
The following list shows the CMS API error responses RFC 7807.
- The
type
,title
,status
andinstance
fields are used only for generic error information. - The
details
field provides a human-readable description of the error - The
code
field provides a machine-readable description of the error. - If an
error
field is included; it indicates that there is an issue with the provided model. Each property on the error object represents a field on the provided model, and the value provides error information about the problem with that field. There is a discrepancy between the name of the property on the error object and the model property.