Cinnamon API Conceptual Description
Accessing the Cinnamon API
All Cinnamon functions that are part of user interaction, e. g. using Cinnamon Desktop Client (CDCplus), are exposed by Cinnamon Server through an HTTP based API (Application Programming Interface).
Cinnamon API sessions begin with a connect command which returns a ticket value if successful. Further API commands require the returned ticket as a parameter to associate the command with an existing session. A session ends with the disconnect command.
Cinnamon Server runs in Apache Tomcat which, by default, listens on port 8080. This can be changed in the Apache Tomcat configuration, if desired.
The Cinnamon API used in current applications is the so-called legacy API. The term legacy had been introduced in the past to distinguish it from another API the server, at that time, exposed. In fact, in current Cinnamon releases, the legacy API is the actual API of the system. The path to the legacy API is /cinnamon/cinnamon/legacy.
Thus, the API URL of a Cinnamon Server is typically:
http://<ip-address>:8080/cinnamon/cinnamon/legacy
NOTE: The Cinnamon Server in default configuration is exposed through an unencrypted http address. In real-life scenarios, Cinnamon Server is either inside a VPN (but even in this case, using https often makes sense), or it is behind a proxy using a certificate and pointing to port 8080 of the target system. In such cases, Cinnamon Server addresses look like this:
https://mycompany.cinnamon-hosting.de/cinnamon/cinnamon/legacy
Request types
See reference (2) for sample code (in C#).
GET requests
A GET request to the Cinnamon Server returns some basic information on the system:
<repositories> <repository> <name>content</name> <categories> <category>production</category> </categories> </repository> <version>3.8.0</version> <build>77</build> </repositories>
The category settings can be configured on the server as required. Clients can use this information to distinguish their behaviour.
POST without content operation
Most API commands are of this category: they read or write information, but do not access the content.
POST with file upload
Some API commands create or change content in the system. In this case, the content must be uploaded as part of the POST request.
POST with file download
The getcontent command is the only API command that retrieves content from the repository. The response of getcontent is therefore the content file requested instead of an XML response.
