What is REST?

Formally, REST describes a way for a client to interact with web resources from a server using a set of stateless operations accessed via URIs.

Though the Cascade CMS v1 REST APi does not exactly follow RESTful API conventions, it is similar enough to be called so. The supported methods are "GET" and "POST". The name of the operation should be included in the URL. The request and response are in JSON format that resembles format of SOAP objects from Cascade CMS's Web Services.

Future version of the API may adhere more closely to REST.

Symbols in this document

{identifier}

Either:

• End of URL string for POST or GET requests: {type}/{id}. Example: folder/2b2fd9bc7f0000010044b22e65131cd3
• End of URL string for POST or GET requests: {type}/{siteName}/{path}.
  Example: page/www.example.com/news/2003/best-of-show
• The identifier can also be provided in body in JSON format for POST requests only.
  Example:

  "identifier": {
    "type": "page",
    "path": {
      "siteId": "2b2fd9a67f0000010044b22e4f6b0859",
      "path": "news/2003/about"
    }
  }

{auth}

Either:

• The user's API Key can be provided within the request's Authorization header as a Bearer token.
  Example: Authorization: Bearer 27c03f58-7c79-45d1-aa8f-76d697bbb10d
• The user's username and password can be provided within the request's Authorization header using a Basic authentication string, which is a base64-encoded string containing username:password.
  Example: Authorization: Basic am9obi5zbWl0aDpqb2huMTIz
• Request parameters u and p for username and password, or apiKey for the user's API Key.
  Examples: u=john.smith&p=john123 OR apiKey=27c03f58-7c79-45d1-aa8f-76d697bbb10d
• Authentication can also be provided in body in JSON format for POST requests only.
  Examples:

  "authentication": {
    "username": "john.smith",
    "password": "john123"
  }

  
  

  "authentication": {
    "apiKey": "27c03f58-7c79-45d1-aa8f-76d697bbb10d"
  }

SOAP vs REST

What are the differences between SOAP and REST?

• When using REST API there is no need for any additional library to handle requests. As long as the specific language can handle JSON and sending requests through the network, that language can use REST API. This opens doors for easy usage of REST API in Javascript and .NET (.NET has a SOAP library but it is hard to set up and it runs into problems), while in PHP there is no need to enable the PHP SOAP module.
• To use web services through SOAP with SSL (URLs with "https://"), additional settings are required in Apache to allow Cascade to connect to itself through SSL so that it can load the WSDL file. No such settings are necessary when using REST API, which reduces the burden on the server administrators.
• There are a few differences between the XML SOAP envelope vs JSON. For instance, null values are returned in XML with xsi:nil="true" attribute while in JSON the null values are simply not there. Another difference is that arrays are wrapped in elements in XML, which then can be interpreted differently by different language specific libraries, while in REST API, the JSON response has plain arrays with elements in them.
• Reading/Editing File assets using REST API uses byte array format whereas SOAP uses base64 encoded format.
• SOAP accepts authentication only in the request body. Using REST API it is allowed to pass authentication to the URL. This is secure for the network over SSL - the credentials will be encrypted so that nobody can intercept the network connection and get the credentials. However, there is a chance that the server itself has logging enabled that stores accessed URLs. At that time, the server administrator could access the logs and see the password. To be 100% sure that the credentials cannot be seen by anyone (even the server administrator), you can pass credentials in the POST request's body. Even the "read" operation is allowed to be executed using POST request.
• An average REST API operation has been reported to take about 30% longer time to execute. This might improve in the future.