Demo 1: Content Access

Demo 1: Content Access

Demo 1 is the "hello world" of the OpenCms JSON API. It showcases simple content access via folder and file URLs. The contents are directly read from the OpenCms virtual file system.

View

The demo 1 app

The approach to display content in the demo 1 app is straightforward, but has some potential drawbacks:

  • If filtering of the content is required, this needs to be implemented in the app.
  • The content manager lacks an user interface that shows him the content that will be included in the app.

These drawbacks are addressed in the demo 2 app using dynamic lists.

Guide to evaluation

  • Open the demo 1 app.
  • Try out the article and the FAQ list and detail views with different locales.
  • Have a look at the article and FAQ demo contents in the OpenCms explorer (requires login).
  • Edit the title of an article or the question of an FAQ entry and see that the changes are immediately reflected in the demo application.
  • Add or delete FAQ entries and articles and see that the contents immediately appear or disappear in the demo application.
  • Read more about the technical details of the JSON folder handler and the content handler in the OpenCms JSON API documentation.
  • Have a look at the source code of the demo 1 app.

Technical details

Accessing the OpenCms file system

The JSON API in it's most basic form allows to access OpenCms contents in the same way as the OpenCms explorer: through the virtual file system. The contents of folders as well as individual content resources can be requested with the JSON API.

Folder URLs return JSON documents showing all child files and child folders along with metadata such as the type or the date of creation. A special JSON API parameter can be used to directly include the contents of the files in the folder.

File URLs return single contents, optionally in a selected locale. If a content is not available for the requested locale, a fallback locale mechanism takes effect. OpenCms supports a large variety of content types that can be nested and linked with each other. Linked contents are automatically resolved in the JSON response document.

Please note that the links in the example(s) below only work if the JSON API is enabled.

The endpoint folder request corresponds to the root folder in the OpenCms explorer.

Endpoint Folder Request

/json/ is the base endpoint of the JSON API, where all JSON contents of an OpenCms installation live.

GET /json/
{
  "shared": {},
  "sites": {},
  "system": {}
}
Sites are available below the /sites/ folder like in the OpenCms explorer.

Site Folder Request

Sites are available below the /sites/ folder. For example, the Mercury demo site /mercury-demo/ is accessible as a sub-site of the default site /sites/default/.

GET /json/sites/default/mercury-demo/
{
  ".content": {},
  ".galleries": {},
  "about": {},
  "advanced-elements": {},
  "blog": {},
  "content-elements": {},
  "demos": {},
  "detail-pages": {},
  "downloads": {},
  "events": {},
  "faqs": {},
  "home": {},
  ..
}
Contents can be found in the .content folder of a site.

Content Folder Request

Contents can be located in the /.content/ folder of a site or sub-site. The example shows the content types of this Mercury demo site.

GET /json/sites/default/mercury-demo/.content/
{
  "article-m": {},
  "contact-m": {},
  "decoy-m": {},
  "event-m": {},
  "faq-m": {},
  ...
}