Building a To-Do List Application (30m)

Variable Substitution

The table below provides substitute values for the variables used in curl command examples.

1.1 UI mockup

We won’t actually be building the web application itself. Instead, we'll focus on defining a simple application object model. The UI mockup provided shows the structure of the app, but the core goal is to highlight how, by simply defining an object type, Contendo Server will provide the necessary API endpoints for you. In many cases, the default object types provided by Contendo Server are sufficient to create a fully functional application.

1.2 Features

1. Add new item
2. Modify item (update task status)
3. Delete item
4. Search for items (Query Language)
5. Pagination

Query Language is basically a SQL-92 standard subset so it should feel very familiar to any developer with some database experience.

2.1 Predefined Object Types:

Contendo Server offers a set of predefined object types:

• Document: Represents standalone content with attached content streams.
• Folder: A container for other objects, such as documents and items.
• Relationship: A directional connection between two objects.
• Policy: Administrative policies applied to objects.
• Item: A generic entity, ideal for modeling To-Do List task objects.

Since our To-Do List task objects are very simple and ambiguous, we will try to use the Item object type as it seems as the best out-of-the-box candidate. Let's take a closer look at this object type in the next step.

3.1 Create toDoTask Object Type

Instead of creating a new object type from scratch, we will leverage Contendo Server's object type inheritance feature. This allows our new object to automatically inherit all properties from the Item object type outlined in the previous section.

{
  "id": "toDoTask",
  "localName": "toDoTask",
  "localNamespace": "https://codenamecode.hr/contendo",
  "displayName": "ToDo Task",
  "queryName": "toDoTask",
  "description": "ToDo Task",
  "parentId": "cmis:item",
  "baseId": "cmis:item",
  "creatable": true,
  "fileable": true,
  "queryable": true,
  "fulltextIndexed": true,
  "includedInSupertypeQuery": true,
  "controllablePolicy": true,
  "controllableACL": true,
  "typeMutability": {
    "create": true,
    "update": true,
    "delete": true
  },
  "propertyDefinitions": {
    "completed": {
      "id": "completed",
      "localName": "completed",
      "displayName": "Completed",
      "queryName": "completed",
      "description": "Task completion status",
      "propertyType": "boolean",
      "cardinality": "single",
      "updatability": "readwrite",
      "inherited": false,
      "required": true,
      "queryable": true,
      "orderable": true,
      "defaultValue": false
    }
  }
}

We can confirm that our new object type inherits from the primary Item object type by examining the values of the baseId and parentId properties. Additionally, we've introduced a new boolean property called completed.

To create toDoTask object type, execute the following curl command:

curl -X -k 'POST' \
  '{REPOSITORY_URL}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'cmisaction=createType' \
  -F 'type={"id":"toDoTask","localName":"toDoTask","localNamespace":"https://codenamecode.hr/contendo","displayName":"ToDo Task","queryName":"toDoTask","description":"ToDo Task","parentId":"cmis:item","baseId":"cmis:item","creatable":true,"fileable":true,"queryable":true,"fulltextIndexed":true,"includedInSupertypeQuery":true,"controllablePolicy":true,"controllableACL":true,"typeMutability":{"create":true,"update":true,"delete":true},"propertyDefinitions":{"completed":{"id":"completed","localName":"completed","displayName":"Completed","queryName":"completed","description":"Task completion status","propertyType":"boolean","cardinality":"single","updatability":"readwrite","inherited":false,"required":true,"queryable":true,"orderable":true, "defaultValue": false}}}'

The response received should contain the newly created object type just like shown in the previous section.

cmisaction is a request parameter used to specify the API method for HTTP POST operations

4.1 Check Repository Info for Root Folder ID

Run the following curl command to get the full repository info:

curl -X -k 'GET' \
  '{REPOSITORY_URL}?cmisselector=repositoryInfo' \
  -H 'X-API-KEY: {API_KEY}'

Received response should be similar to the following JSON object with some parts omitted for brevity:

{
  "toDoList1": {
    "repositoryId": "toDoList1",
    "repositoryName": "toDoList1",
    "repositoryDescription": "toDoList1",
    "vendorName": "codenamecode d.o.o.",
    "productName": "Contendo Server",
    "productVersion": "2024.4",
    "rootFolderId": "482b93df-6836-45fb-8963-82c20aa6e618",
    "capabilities": {},
    "aclCapabilities": {},
    "latestChangeLogToken": "a44bc091-729a-4451-abf1-3b35f83a3efd",
    "cmisVersionSupported": "1.1",
    "changesIncomplete": true,
    "changesOnType": [
      "cmis:folder",
      "cmis:document",
      "cmis:item",
      "cmis:policy",
      "cmis:relationship"
    ],
    "principalIdAnonymous": "anonymous",
    "principalIdAnyone": "anyone",
    "extendedFeatures": [],
    "repositoryUrl": "{REPOSITORY_URL}",
    "rootFolderUrl": "{REPOSITORY_URL}/root"
  }
}

We won’t dive into the details of each section of the response. Instead, we’ll focus on locating the rootFolderId property and use its value for the FOLDER_ID variable.

Run the following curl command to create our first To-Do task:

curl -X -k 'POST' \
  '{REPOSITORY_URL}/root' \
  -H 'Content-Type: multipart/form-data' \
  -F 'cmisaction=createItem' \
  -F 'succinct=true' \
  -F 'objectId={FOLDER_ID}' \
  -F 'properties={"cmis:name":"Buy Some Food","cmis:description":"1kg Potato, 1 Load of Bread","cmis:objectTypeId":"toDoTask"}'

Received response should be similar to the following JSON object confirming the creation of the new toDoTask object:

{
  "succinctProperties": {
    "cmis:baseTypeId": "cmis:item",
    "cmis:changeToken": "d22fcecd-1c1d-4628-8476-e196474a149e",
    "cmis:createdBy": "super",
    "cmis:creationDate": 1740057831703,
    "cmis:description": "1kg Potato, 1 Load of Bread",
    "cmis:lastModificationDate": 1740057831703,
    "cmis:lastModifiedBy": "super",
    "cmis:name": "Buy Some Food",
    "cmis:objectId": "3c28b871-ce03-4cd7-8f72-25abf324eb30",
    "cmis:objectTypeId": "toDoTask",
    "cmis:secondaryObjectTypeIds": null
  }
}

4.2. HTTP POST Method Content-Type

POST base HTTP methods support two types of HTTP Content-Type: multipart/form-data and application/x-www-form-urlencoded. The example above demonstrates an additional feature supported by the Contendo Server by sending all properties as a JSON in a single properties field when creating or updating objects.

There are more than 50 API methods available for repository objects manipulation.

Now you have one task in your To-Do List. Let's create the other task from our UI mockup in the next step.

6.1 Pagination

We can observe that the response includes details about our two tasks, along with additional information such as the total number of items and an indication of whether there are more items available beyond the current page. This is how we implement the pagination feature.

Contendo Server streamlines pagination implementation by enabling two additional request parameters, maxItems and skipCount for various API methods, including the children method demonstrated above. Use maxItems to define the page size and skipCount to specify the offset.

7.1 Change Token

All primary object types include an opaque string property, cmis:changeToken, which is used for optimistic locking and concurrency checking, ensuring that user updates do not conflict. The following command, which updates the status of a given task, makes use of the changeToken request parameter.

A new change token is assigned to an object upon its creation and after an update has been made.

7.2 Update Task's Status

To update the status of a toDoTaskobject, execute the following curl command:

# Request variable mapping
# ------------------------
# OBJECT_ID = object's cmis:objectId property value
# OBJECT_CHANGE_TOKEN = object's cmis:changeToken property value

curl -X -k 'POST' \
  '{REPOSITORY_URL}/root' \
  -H 'Content-Type: multipart/form-data' \
  -F 'cmisaction=update' \
  -F 'changeToken={OBJECT_CHANGE_TOKEN}' \
  -F 'objectId={OBJECT_ID}' \
  -F 'succinct=true' \
  -F 'properties={"completed":true}'

Response

The updated toDoTask object will be returned in JSON format, reflecting the new status:

{
  "succinctProperties": {
    "cmis:secondaryObjectTypeIds": null,
    "cmis:baseTypeId": "cmis:item",
    "cmis:changeToken": "202fcf25-805a-46ca-a6b4-f50d0581f5bc",
    "cmis:createdBy": "user1",
    "cmis:creationDate": 1740405145014,
    "cmis:description": "1kg Potato, 1 Load of Bread",
    "cmis:lastModificationDate": 1740406408917,
    "cmis:lastModifiedBy": "user1",
    "cmis:name": "Buy Some Food",
    "cmis:objectId": "76710911-9201-4ef3-b27f-784bf0deedeb",
    "cmis:objectTypeId": "toDoTask",
    "completed": true
  }
}

8.1 Fetch by Object ID

curl -X -k 'GET' \
  '{REPOSITORY_URL}/root?objectId={OBJECT_ID}&succinct=true&cmisselector=object' \
  -H 'X-API-KEY: {API_KEY}'

8.2 Fetch by Object Path

curl -X -k 'GET' \
  '{REPOSITORY_URL}/root/{OBJECT_NAME}?succinct=true&cmisselector=object' \
  -H 'X-API-KEY: {API_KEY}'

Several Contendo Server API methods also support using the object path in place of the objectId request parameter.

The path to an object can be specified as follows: /{domain_name}/{repository_id}/root/{folder_1_name}/.../{folder_n_name}/{object_name}.

This hierarchical structure defines the object's location within the domain repository, starting from the root folder and traversing through nested folders to the specific object.

Path to the root folder is always given as /{domain_name}/{repository_id}/root.

8.3 Fetch Using Query Language (Search)

curl -X -k 'POST' \
  '{REPOSITORY_URL}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'cmisaction=query' \
  -F 'succinct=true' \
  -F 'statement=SELECT cmis:name, cmis:description FROM toDoTask where cmis:objectId='\''{OBJECT_ID}'\'''

At the start of this tutorial, we introduced an input field for searching tasks. The statement field value from the curl request above represents what you would enter to search for tasks. This is how we implement the search functionality.

The query will always return a list of results with only the properties you request. Use an asterisk (*) in the SELECT clause to retrieve all properties.