[[PageOutline(3,API methods,pullout)]]
= Cinnamon Application Programming Interface (API)
> **NOTE:** This documentation is under construction.

See [wiki:Public/Docs/CinnamonApiConceptualDescription Cinnamon API conceptual description] for general information how to use the API.

== Methods by name
=== attachlifecycle
=== changestate 
=== connect
==== Parameters
||=**Field** =||=**Value** =||
||{{{command}}}    ||{{{connect}}}        ||
||{{{repository}}}    ||Name of the repository.        ||
||{{{user}}}    ||User name.        ||
||{{{password}}}    ||User password.        ||
||{{{machine}}}    ||Machine name of the client machine.        ||

==== Return value
The {{{connect}}} command returns an XML structure like this:
{{{#!xml
<connection>
  <ticket>319b75df-9840-4316-9647-f34625eb5515@content</ticket>
</connection>
}}}

The {{{<ticket>}}} element contains the session ticket the server has assigned. The client application must remember the ticket and use it as a parameter for all subsequent API calls, including {{{disconnect}}}.

{{{#!comment
TODO: to be documented what can go wrong (false credentials etc.).
}}}

==== Description
The {{{connect}}} command establishes a session with the server and returns the session ticket.

=== copy
=== copytoexisting
FIXME The documentation for the {{{copytoexisting}}} command is under construction.
==== Parameters
||=**Field** =||=**Value** =||
||{{{command}}}    ||{{{copytoexisting}}}        ||
||{{{sourceid}}}    ||ID of the object whose content and / or metadata is to be copied.        ||
||{{{targetid}}}    ||ID of the target object to write the source data into. The target object can be any version of an existing object.        ||
||{{{copymetasets}}}    ||Comma separated list of metaset names that should be copied from source to target. The parameter is optional, if it is left out, no metasets will be copied.        ||
||{{{copycontent}}}    ||{{{true}}} to copy content, {{{false}}} to copy metasets only.        ||
||{{{ticket}}}    ||Session ticket.        ||

==== Return value
The {{{copytoexisting}}} command returns an XML structure like this:
TODO
{{{#!xml
<see_what_happens/>
}}}

TODO: explain.

{{{#!comment
TODO: to be documented what can go wrong (false credentials etc.).
}}}

==== Description
The {{{copytoexisting}}} command copies content and / or metadata from the object specified by {{{sourceid}}} to an existing object specified by {{{targetid}}}. The boolean {{{copycontent}}} parameter controls whether the content should be copied or not. The optional {{{copymetasets}}} parameter controls the metasets to be copied, specified as a comma separated list of metaset names.

TODO: is a lock required?


=== createlink
=== create
=== createfolder
=== createrelation
=== delete
=== deleteallversions
=== deletefolder
=== deletelink
=== deleterelation
=== detachlifecycle 
=== disconnect
==== Parameters
||=**Field** =||=**Value** =||
||{{{command}}}    ||{{{disconnect}}}        ||
||{{{ticket}}}    ||Session ticket to disconnect.        ||

==== Return value
The {{{disconnect}}} command returns an XML structure like this:
{{{#!xml
<success>success.disconnect</success>
}}}

{{{#!comment
TODO: to be documented what can go wrong (error.disconnect?).
}}}

==== Description
The {{{disconnect}}} command ends an existing session, identified by its {{{ticket}}}.

=== echo
> **NOTE:** echo has no legacy action.
=== getacls
> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods. 
=== getconfigentry
=== getcontent
==== Parameters
||=**Field** =||=**Value** =||
||{{{command}}}    ||{{{getcontent}}}        ||
||{{{id}}}    ||ID of the object whose content is to be retrieved.        ||
||{{{ticket}}}    ||Session ticket to disconnect.        ||

==== Return value
The {{{getcontent}}} command returns a stream with the content of the object. Typically, it is written to a file.

{{{#!comment
TODO: to be documented what can go wrong (wrong id etc.).
}}}

==== Description
The {{{getcontent}}} retrieves the content of an object identified by its {{{id}}}. {{{getcontent}}} is the only command returning file content instead of an XML structure.


=== getfolder
=== getfolderbypath
==== Parameters
||=**Field** =||=**Value** =||
||{{{command}}}    ||{{{getfolderbypath}}}        ||
||{{{path}}}    ||[wiki:Public/Docs/CinnamonFolderPaths Path] to the folder.        ||
||{{{include_summary}}}    ||{{{true}}} returns [wiki:Public/Docs/CinnamonSummary summary ] with each object, [[br]]{{{false}}} does not. [[br]]The parameter can be omitted, the default is {{{false}}}.       ||
||{{{ticket}}}    ||Session ticket.        ||

==== Return value
The {{{getfolderbypath}}} command returns an [wiki:Public/Docs/CinnamonFolderXml XML representation of the folder] with the given path.

{{{#!comment
TODO: to be documented what can go wrong (wrong id etc.).
}}}



=== getfoldermeta
=== getfoldersbyid
=== getfoldertypes
> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods. 
=== getformats
=== getmeta
==== Parameters
||=**Field** =||=**Value** =||
||{{{command}}}    ||{{{getmeta}}}        ||
||{{{id}}}    ||ID of the object whose metadata is to be retrieved.        ||
||{{{ticket}}}    ||Session ticket.        ||

==== Return value
The {{{getmeta}}} command returns the [wiki:Public/Docs/CinnamonMetadata metadata] of the object with the specified id. {{{getmeta}}} does not support folders, use the [#getfoldermeta getfoldermeta] command instead, or retrieve a specific metaset with [#getmetaset getmetaset] (which also works for folders).

{{{#!comment
TODO: to be documented what can go wrong (wrong id etc.).
}}}



=== getmetaset
==== Parameters
||=**Field** =||=**Value** =||
||{{{command}}}    ||{{{getmetaset}}}        ||
||{{{id}}}    ||ID of the object whose metadata is to be retrieved.        ||
||{{{class_name}}}    ||{{{OSD}}} (**O**bject **S**ystem **D**ata) to retrieve an object metaset, {{{Folder}}} to retrieve a folder metaset.        ||
||{{{type_name}}}    ||Name of the metaset type to be retrieved.        ||
||{{{ticket}}}    ||Session ticket.        ||

==== Return value
The {{{getmetaset}}} command returns one metaset of the [wiki:Public/Docs/CinnamonMetadata metadata] of the object or folder with the specified id.

{{{#!comment
TODO: to be documented what can go wrong (wrong id etc.).
}}}



=== getobject
=== getobjects
==== Parameters
||=**Field** =||=**Value** =||
||{{{command}}}    ||{{{getobjects}}}        ||
||{{{parentid}}}    ||ID of the parent folder of the objects to be retrieved.        ||
||{{{include_summary}}}    ||{{{true}}} returns [wiki:Public/Docs/CinnamonSummary summary ] with each object, [[br]]{{{false}}} does not. [[br]]The parameter can be omitted, the default is {{{false}}}.       ||
||{{{versions}}}    ||{{{all}}} to return all [wiki:Public/Docs/CinnamonVersioning versions], [[br]]{{{branch}}} to return only the end nodes of branches, [[br]]{{{head}}} to return only the latest versions of the returned objects.        ||
||{{{ticket}}}    ||Session ticket.        ||

==== Return value
The {{{getobjects}}} command returns the objects inside the given parent folder as an [wiki:Public/Docs/CinnamonObjectXml XML representation].

{{{#!comment
TODO: to be documented what can go wrong (wrong id etc.).
}}}



=== getobjectsbyid
=== getobjtypes
> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods. 
=== getrelations
=== getrelationtypes
> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods. 
=== getsubfolders
==== Parameters
||=**Field** =||=**Value** =||
||{{{command}}}    ||{{{getsubfolders}}}        ||
||{{{parentid}}}    ||ID of the parent folder of the subfolders to be retrieved.[[br]]      The value {{{0}}} returns the subfolders of the root folder. ||
||{{{include_summary}}}    ||{{{true}}} returns [wiki:Public/Docs/CinnamonSummary summary ] with each object, [[br]]{{{false}}} does not. [[br]]The parameter can be omitted, the default is {{{false}}}.       ||
||{{{ticket}}}    ||Session ticket.        ||

==== Return value
The {{{getsubfolders}}} command returns the subfolders inside the given parent folder as an [wiki:Public/Docs/CinnamonFolderXml XML representation].

{{{#!comment
TODO: to be documented what can go wrong (wrong id etc.).
}}}


=== getusers
> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods. 
=== getuserspermissions
=== listaclentries
> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods. 
=== listgroups
> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods. 
=== listindexgroups
> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods. 
=== listindexitems
> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods. 
=== listlanguages
> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods. 
=== listlifecycles
> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods. 
=== listmetasettypes
> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods. 
=== listuilanguages
> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods. 
=== lockobject
==== Parameters
||=**Field** =||=**Value** =||
||{{{command}}}    ||{{{lockobject}}}        ||
||{{{id}}}    ||ID of the object to be locked.        ||
||{{{ticket}}}    ||Session ticket.        ||

==== Return value
The {{{lockobject}}} returns {{{<success/>}}} or an {{{<error/>}}} element containing a message.

==== Description
The {{{lockobject}}} command places a write lock on the object identified by the {{{id}}} parameter.

=== renderindexedosd
> **NOTE:** New in build 117. 
=== renderindexedfolder
> **NOTE:** New in build 117. 
=== searchfolders
=== searchobjectids
=== searchobjects
==== Parameters
||=**Field** =||=**Value** =||
||{{{command}}}    ||{{{searchobjects}}}        ||
||{{{ticket}}}    ||Session ticket.        ||
||{{{query}}}    ||Native Lucene XML query.        ||
||{{{include_summary}}}    ||{{{true}}} returns [wiki:Public/Docs/CinnamonSummary summary ] with each object, [[br]]{{{false}}} does not. [[br]]The parameter can be omitted, the default is {{{false}}}.       ||
||{{{page_size}}}    ||[optional] Maximal number of objects to returned.        ||
||{{{page}}}    ||[optional] Zero-based index of the page to return, this parameter may only be set if {{{page_size}}} has also been set.         ||

==== Return value
The {{{searchobjects}}} command returns an [wiki:Public/Docs/CinnamonObjectXml XML structure] like this:
{{{#!xml
<objects total-results="15">
  <object>
    <!-- XML representation of an object -->
  </object>
  <object>
    <!-- XML representation of an object -->
  </object>
  <!-- 13 more objects -->
</objects>
}}}

{{{#!comment
TODO: to be documented what can go wrong .
}}}

==== Description
The {{{searchobjects}}} command executes a search using a Lucene XML query and returns the objects found as an XML structure.

=== setchangedstatus
=== setcontent
==== Parameters
||=**Field** =||=**Value** =||
||{{{command}}}    ||{{{setcontent}}}        ||
||{{{id}}}    ||ID of the object whose content is to be uploaded.        ||
||{{{format}}}    ||System name of the format whose content is to be uploaded.        ||
||{{{ticket}}}    ||Session ticket to disconnect.        ||

==== Return value
The {{{setcontent}}} command command returns {{{<success/>}}} or an {{{<error/>}}} element containing a message.

{{{#!comment
TODO: to be documented what can go wrong (wrong id etc.).
}}}

==== Description
The {{{setcontent}}} command uploads content of the format identified by {{{format}}} to an existing object identified by its {{{id}}}. {{{setcontent}}} sends the file content stream to the server.


=== setmeta
=== setmetaset
=== setpassword
=== setsummary
=== setsysmeta
=== unlockobject
==== Parameters
||=**Field** =||=**Value** =||
||{{{command}}}    ||{{{unlockobject}}}        ||
||{{{id}}}    ||ID of the object to be unlocked.        ||
||{{{ticket}}}    ||Session ticket.        ||

==== Return value
The {{{unlockobject}}} command returns {{{<success/>}}} or an {{{<error/>}}} element containing a message.

==== Description
The {{{unlockobject}}} command removes a write lock on the object identified by the {{{id}}} parameter.

=== updatefolder
=== updatelink
=== version

== Deprecated methods
=== checktranslation [deprecated]
> **IMPORTANT:** This API method is deprecated and will be removed in a future release without further notice. 
This method is highly special, can be replaced with other API methods and the render mechanism it supports is deprecated. Some customers still use it.
=== createtranslation [deprecated]
> **IMPORTANT:** This API method is deprecated and will be removed in a future release without further notice. 
This method is highly special, can be replaced with other API methods and the render mechanism it supports is deprecated. Some customers still use it.
=== forksession  [deprecated]
> **IMPORTANT:** This API method is deprecated and will be removed in a future release without further notice. 
It is no longer used in client libraries and there seems to be no use case.
=== getsysmeta  [deprecated]
> **IMPORTANT:** This API method is deprecated and will be removed in a future release without further notice. 
All such data is returned by {{{getobject}}} or other API methods returning objects.=== startrendertask [deprecated]
> **IMPORTANT:** This API method is deprecated and will be removed in a future release without further notice. 
This method is highly special, can be replaced with other API methods and the render mechanism it supports is deprecated. Some customers still use it.
=== sudo [deprecated]
> **IMPORTANT:** This API method is deprecated and will be removed in a future release without further notice. 
The entire sudo functionality has become obsolete with the change tracking logic.