= Cinnamon API Conceptual Description
== Accessing the Cinnamon API
All Cinnamon functions that are part of user interaction, e. g. using [wiki:Docs/CinnamonDesktopClient Cinnamon Desktop Client (CDCplus)], are exposed by Cinnamon Server through an [https://www.w3schools.com/whatis/whatis_http.asp 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:
{{{#!xml
<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.

== References
* (1) [wiki:Docs/CinnamonApi Cinnamon API Command Reference]
* (2) [https://sourceforge.net/p/cinnamon/code/HEAD/tree/Client/trunk/NativeApiServerConnector/ServerCommandInterface.cs Source code of ServerCommandInterface.cs]