Introduction

​

What for?

The Content Delivery API is the API that allows your website or app to show content to end-users. It is (mostly) a read-only API built for high scalability, though it does support various write operations.

If you are looking for an API to integrate into your management tooling, have a look at our Studio API.

​

Get Started

Unlike the Studio API, the Content Delivery API does not offer a REST interface in the traditional sense, as it uses a protocol called Connect. But do not worry! The API still works with standard GET and POST requests, and will return standard JSON. The primary difference with REST is that the API routes look a little different than you may be used to.

​

GET requests

To understand how to use Motto’s Content Delivery API using standard HTTP GET requests for read-only operations, please follow along with a basic example.

Let’s say we want to get a list of all events in the project, you would send a GET request to the following URL:

https://cda.mottostreaming.com/motto.cda.cms.event.v1.EventService/ListEvents?encoding=json&message=%7B%22pageSize%22%3A%2225%22%7D

This URL is broken down as follows:

1. https://cda.mottostreaming.com -> This is the base URL of the API. Should look familiar, so far!
2. motto.cda.cms.event.v1.EventService -> This is the “package” and “service” of the API. It tells Motto servers which part of the API you are trying to access. You can find all available packages here.
3. ListEvents -> This is the “method” of the API. It tells the API which specific operation you are trying to perform. You can find all available methods on page linked in step (2), after selecting a package.
4. ?encoding=json&message=%7B%22pageSize%22%3A%2225%22%7D -> This is the query string of the API. It tells the API which parameters you are trying to pass to the method. In this case, we are passing a JSON object with a pageSize of 25, since that’s what this example endpoint requires. Please note that the JSON should always be URL-encoded, and should be included in the message parameter (you should not change the encoding parameter)! To know which parameters are needed for each method, you can click into a method’s Request, e.g. for list events.

Putting this together, such a request would look like this using curl:

curl -X GET 'https://cda.mottostreaming.com/motto.cda.cms.event.v1.EventService/ListEvents?encoding=json&message=%7B%22pageSize%22%3A%2225%22%7D' \
  -H 'Authorization: Bearer <PUBLIC_KEY>'

To understand more about the Authorization header, please see the authentication section.

You now know how to perform GET requests to the Content Delivery API. However, some operations require POST requests, which we will cover in the next section.

​

POST requests

To understand how to use Motto’s Content Delivery API using standard HTTP POST requests for write operations, please follow along with a basic example.

Let’s say we want to obtain a Motto JWT for a user that has signed in using Userfront (a third party user management service). From the above section, we know how to navigate to the necessary API endpoint, which in this case can be found here.

As we can see in the documentation for this endpoint, this is not marked with NO_SIDE_EFFECTS, which means it is not a cacheable request. Therefore, we need to use a POST request. Such a request would look like this using curl:

curl -X POST 'https://cda.mottostreaming.com/motto.cda.iam.auth.v1.AuthService/ExchangeToken' \
  -H 'authorization: Bearer <PUBLIC_KEY>' \
  -H 'connect-protocol-version: 1' \
  -H 'content-type: application/json' \
  --data-raw '{"userfrontIdToken":"eyJhb....nEa-V8"}'

Note that now, as with normal REST POST requests, the parameters are no longer included in the URL, but in the body of the request. The body should always be a JSON object.

If you still have questions about how to use the Content Delivery API, please do not hesitate to contact us.

​

Full API documentation

For a full list of all available methods and services, please visit our API documentation.

If you are unsure about how to use this API documentation, please follow the examples above.