Changes between Initial Version and Version 1 of Public/Docs/CinnamonApiConceptualDescription

Timestamp:

Sep 11, 2019, 10:13:29 AM (5 years ago)

Author:

Administrator

Comment:

—

Public/Docs/CinnamonApiConceptualDescription

@@ +1 @@
+= 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]