Node URLs

The Application Server supports retrieval of nodes and node attachments via URLs and takes responsibility for setting headers and cache state for optimal performance. This method is the preferred method for dealing with binary payloads as it ensures compatibility with CDN edge caching.

In addition, binary and JSON files that are retrieved from the Cloud CMS API are cached on the Application Server itself so that subsequent requests benefit from having a local copy. A notifications layer using Amazon SQS allows the Application Server to listen for API-side content changes so as to invalidate cache and keep consistent state.

Nodes retrieved via URLs can either be statically retrieved (/static) or they can be transformed on-the-fly into alternate preview renditions (/preview). Both are covered below.

Static Retrieval

The /static URL prefix supports the direct, non-transformation method of getting content from the Cloud CMS API via the URL.

Routes

We recommend you use the following request structure:

GET /static/{filename}?repository={repositoryId}&branch={branchId}&node={nodeId}
GET /static/{filename}?repository={repositoryId}&branch={branchId}&path={path}

These routes are preferred because they let you set the filename to any value you like so as to establish your own uniqueness and cache-keys for CDN and browser-based caching. For example, the following URLs are valid:

GET /static/user/image.png?repository=4cfc984c52da02ebbcec&branch=60f993014617fac188fa&path=/My Folder/My Images/image1.png
GET /static/user/avatar.png?repository=4cfc984c52da02ebbcec&branch=60f993014617fac188fa&node=e375c699a15055749102&attachment=avatar

The first example pulls down the default attachment for the identified node. The browser and any proxy servers between Cloud CMS and your end user will see the resource as /static/user/image.png.

The second example pulls down the avatar attachment for the identified node. The browser and any proxy servers between Cloud CMS and your end user will see the resource as /static/user/avatar.png.

In addition, the following legacy routes will work. These are supported so that older applications will continue to work. While they offer similar functionality as the URLs mentioned above, these are not recommended as they encode the node path into the URI in a way that limits the filenames allowed in paths. In other words, they won't work for all of your content nodes - especially once you start to use the I18N features of Cloud CMS (i.e. large character sets, Chinese, Arabic and so forth).

GET /static/node/{nodeId}
GET /static/node/{nodeId}/{attachmentId}
GET /static/node/{nodeId}/{attachmentId}/{filename}
GET /static/path/{path}
GET /static/repository/{repositoryId}/branch/{branchId}/node/{nodeId}
GET /static/repository/{repositoryId}/branch/{branchId}/node/{nodeId}/{attachmentId}
GET /static/repository/{repositoryId}/branch/{branchId}/node/{nodeId}/{attachmentId}/{filename}
GET /static/repository/{repositoryId}/branch/{branchId}/path/{path}

In all cases, the following request parameters are optional:

  • metadata if set to true, the JSON will be downloaded for the node instead of any attachments
  • full if set to true, the full JSON object is downloaded including system recordset data
  • attachment overrides and specifies the attachment ID to be retrieved
  • force forces any cache state to invalidate so that objects are retrieved from Cloud CMS anew
  • a if set to true, forces the Content-Disposition header to be set
  • fallback provides a URL to fallback to if the attachment cannot be found

Here is an example where we retrieve the metadata for a node (identified by path):

GET /static/user/image.png.json?repository=4cfc984c52da02ebbcec&branch=60f993014617fac188fa&metadata=true&path=/My Folder/My Images/image1.png

And here is doing so using the node ID:

GET /static/user/image.png.json?repository=4cfc984c52da02ebbcec&branch=60f993014617fac188fa&metadata=true&node=e375c699a15055749102

If the node cannot be found, we can use the fallback option to redirect somewhere else (such as a locally hosted placeholder image):

GET /static/user/image.png?repository=4cfc984c52da02ebbcec&branch=60f993014617fac188fa&node=e375c699a15055749102&fallback=/default-avatar.png

When you request something via these routes, the Cloud CMS Application Server will cache the asset on disk so that it doesn't have to go back over the wire to the Cloud CMS API the next time around. This yields performance benefits for your application. This process pays attention to cache headers and makes sure that the version available on the Cloud CMS Application Server is consistent with your the expectations from within the API.

However, there may be times when you wish to force a refresh of the cache on the Cloud CMS Application Server. You can do this by using the force option, like this:

GET /static/user/image.png?repository=4cfc984c52da02ebbcec&branch=60f993014617fac188fa&node=e375c699a15055749102&force=true

Note that in all of these cases, the filename can be set to anything you like. In the example above, the filename is /static/user/image.png. The Cloud CMS Application Server ignores the filename and leaves it for the browser or CDN to work with to determine uniqueness.

If you do not provide a filename, things will still work. However, you may not be able to take full advantage of CDN and browser-based caching. Consider using a filename when generating your URLs.

By Node ID

If you've configured your gitana.json file with an application ID, then you can retrieve node content simply using the Node ID. The content repository from the application's stack will automatically be used for any retrieval.

GET /static?node={nodeId}

This will retrieve the default attachment for a node.

GET /static?node={nodeId}&attachment={attachmentId}

This retrieves the given attachment for a node.

GET /static/{filename}?node={nodeId}&attachment={attachmentId}

This retrieves the given attachment for a node and sets the filename to {filename} when downloaded by the browser.

By Node Path

Similarly, you can retrieve nodes using their path:

GET /static?path={path}
GET /static/{filename}?path={path}

This will find the node at the given path offset from the root of the repository. The second example specifies the filename that the browser/CDN will see.

By Node ID (for a specific repository and branch)

If you haven't configured the application setting within your gitana.json configuration file or if you'd simply like to fetch content from a different place, you can do so.

GET /static?repository={repositoryId}&branch={branchId}&node={nodeId}

This will retrieve the default attachment for a node.

GET /static?repository={repositoryId}&branch={branchId}&node={nodeId}&attachment={attachmentId}

This retrieves the given attachment for a node.

GET /static/{filename}?repository={repositoryId}&branch={branchId}&node={nodeId}&attachment={attachmentId}

This retrieves the given attachment and sets things up so that the browser downloads as {filename}.

By Node ID (for a specific repository and branch)

Similarly, you can retrieve nodes using their path:

GET /static/{filename}?repository={repositoryId}&branch={branchId}&path={path}

This retrieves the default attachment for the node at the given path.

Preview Retrieval

The /preview URL prefix supports on-the-fly transformation, attachment generation and caching of assets from the Cloud CMS API via the URL. Preview URLs are a bit more expensive to run the first time since they allow for resizing, mimetype conversions and other enhancements.

If you're just looking to retrieve assets, your fastest bet is the /static prefix. However, if you want to resizing things on the fly, convert to other document types, etc, then use /preview.

Routes

The preview routes are similar to the static routes. All of the same /static functionality is supported and the URL structures are essentially the same.

We recommend the following URL formats:

 GET /preview/{filename}?repository={repositoryId}&branch={branchId}&node={nodeId}
 GET /preview/{filename}?repository={repositoryId}&branch={branchId}&path={path}

In addition, as with the static case, we support the following legacy formats:

 GET /preview/node/{nodeId}
 GET /preview/node/{nodeId}/{name}
 GET /preview/path/{path...}
 GET /preview/repository/{repositoryId}/branch/{branchId}/node/{nodeId}/{name}
 GET /preview/repository/{repositoryId}/branch/{branchId}/path/A/B/C/D/{name}

As with the static case, the following request parameters are optional:

  • metadata if set to true, the JSON will be downloaded for the node instead of any attachments
  • full if set to true, the full JSON object is downloaded including system recordset data
  • attachment overrides and specifies the attachment ID to be retrieved
  • force forces any cache state to invalidate so that objects are retrieved from Cloud CMS anew
  • a if set to true, forces the Content-Disposition header to be set
  • fallback provides a URL to fallback to if the attachment cannot be found

The following request parameters are available for Preview URLs only:

  • name the name of the generated preview attachment to be stored
  • mimetype the desired mimetype for the resource to be transformed into
  • size for images, the width in px of the response image

When you request a preview of a node attachment, the attachment will be retrieved and then transformed on the fly. A transformation includes resizing and mimetype conversion. Once the transformation is generated, it will be written back to your node as a new attachment. If name is provided, then it will be used to determine the attachment name used to store the generated transformation. If name is not provided, an attachment ID will be reasoned out on the fly as well.

Here is an example where we retrieve an image, convert it to JPEG and resize it to 256px width all in a single request:

GET /preview/user/image.jpeg?repository=4cfc984c52da02ebbcec&branch=60f993014617fac188fa&attachment=image&name=image2&mimetype=image/jpeg&size=256&path=/My Folder/My Images/image1.png

In this case, the image attachment is sourced from. This is transformed into image/jpeg and resized to width 256px.
The result is stored as the attachment image2 on the node. It is also cached within the Cloud CMS application server. As you make changes to things, Cloud CMS automatically invalidates caches for you. For example, if you were to modify the image2 attachment, any previews that were generated are discarded. And the Cloud CMS Application Server will also discard its cached state for those nodes (once notified via Amazon SQS which happens automatically in the background).

The name parameter is optional. If you don't provide one, Cloud CMS will come up with one for you. This means you can accomplish the same thing like this.

GET /preview/user/image.jpeg?repository=4cfc984c52da02ebbcec&branch=60f993014617fac188fa&attachment=image&mimetype=image/jpeg&size=256&path=/My Folder/My Images/image1.png

If you do, for any reason, want to know the attachment ID of the cached attachment, you can provide it via the name attribute. Otherwise, don't bother.

By Node ID

If you've configured your gitana.json file with an application ID, then you can retrieve node content simply using the Node ID. The content repository from the application's stack will automatically be used for any retrieval.

GET /preview?node={nodeId}&name=image256&size=256

This generates a preview of the default attachment, resizes to 256px (assuming it is an image) and writes the results into an attachment named image256. Subsequent requests will reuse the previously generated attachment.

GET /preview/{filename}?node={nodeId}&size=256&name=image256&attachment=myimage&mimetype=image/jpeg

This generates a preview of the myimage attachment, resizes to 256px (assuming it is an image) and converts to image/jpeg. The result is written to the image256 attachment. Subsequent requests will reuse the image256 attachment. The filename is optional and gives you the ability to control the cache key for browsers and CDN.

By Node Path

Similarly, you can generate previews using node paths:

GET /preview?path={path}&name=pdf&mimetype=application/pdf

This will find the node with the given path, take its default attachment and transform to PDF. The result is written to the pdf attachment and streamed back.

On a Specific Branch

All content is retrieved by default using the branch that is configured for your web project. By default this is the master branch. However, you can have your static and preview-based retrieve pull from other branches in any of the following ways:

  1. Pass the `branch' request parameter along with each request, or...
  2. Pass the CLOUDCMS_BRANCH request header along with each request, or...
  3. Pass the BRANCH request header along with each request, or...
  4. Pass the branchId request header along with each request

In any of these cases, the request parameter or header value should be the ID of the branch.

You can also set a cookie to identify the branch.

cloudcms-server-application-{applicationId}-branch-id

Where applicationId is the ID of your application as registered in Cloud CMS. In this way, a single browser can preview different branches on different applications running against Cloud CMS, each with their own identified branch ID.

Specific Repository + Branch

If you haven't configured the application setting within your gitana.json configuration file or if you'd simply like to fetch content from a different place, you can do so by providing the repositoryId and branchId of your content.

GET /static/{filename}?repository={repositoryId}&branch={branchId}&node={nodeId}    
GET /static/{filename}?repository={repositoryId}&branch={branchId}&path={path}
GET /preview/{filename}?repository={repositoryId}&branch={branchId}&node={nodeId}    
GET /preview/{filename}?repository={repositoryId}&branch={branchId}&path={path}

These work the same as the other cases but are specific to a known repository and branch. Bear in mind that permissions are checked for all content fetches. Make sure that your application user has rights to other repositories and branches.