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


Ignore:
Timestamp:
Sep 11, 2019, 10:01:15 AM (6 years ago)
Author:
Administrator
Comment:

—

Legend:

Unmodified
Added
Removed
Modified

  • Public/Docs/CinnamonApi

    v1 v1  
     1[[PageOutline(3,API methods,pullout)]]
     2= Cinnamon Application Programming Interface (API)
     3> **NOTE:** This documentation is under construction.
     4
     5See [wiki:Public/Docs/CinnamonApiConceptualDescription Cinnamon API conceptual description] for general information how to use the API.
     6
     7== Methods by name
     8=== attachlifecycle
     9=== changestate
     10=== connect
     11==== Parameters
     12||=**Field** =||=**Value** =||
     13||{{{command}}}    ||{{{connect}}}        ||
     14||{{{repository}}}    ||Name of the repository.        ||
     15||{{{user}}}    ||User name.        ||
     16||{{{password}}}    ||User password.        ||
     17||{{{machine}}}    ||Machine name of the client machine.        ||
     18
     19==== Return value
     20The {{{connect}}} command returns an XML structure like this:
     21{{{#!xml
     22<connection>
     23  <ticket>319b75df-9840-4316-9647-f34625eb5515@content</ticket>
     24</connection>
     25}}}
     26
     27The {{{<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}}}.
     28
     29{{{#!comment
     30TODO: to be documented what can go wrong (false credentials etc.).
     31}}}
     32
     33==== Description
     34The {{{connect}}} command establishes a session with the server and returns the session ticket.
     35
     36=== copy
     37=== copytoexisting
     38FIXME The documentation for the {{{copytoexisting}}} command is under construction.
     39==== Parameters
     40||=**Field** =||=**Value** =||
     41||{{{command}}}    ||{{{copytoexisting}}}        ||
     42||{{{sourceid}}}    ||ID of the object whose content and / or metadata is to be copied.        ||
     43||{{{targetid}}}    ||ID of the target object to write the source data into. The target object can be any version of an existing object.        ||
     44||{{{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.        ||
     45||{{{copycontent}}}    ||{{{true}}} to copy content, {{{false}}} to copy metasets only.        ||
     46||{{{ticket}}}    ||Session ticket.        ||
     47
     48==== Return value
     49The {{{copytoexisting}}} command returns an XML structure like this:
     50TODO
     51{{{#!xml
     52<see_what_happens/>
     53}}}
     54
     55TODO: explain.
     56
     57{{{#!comment
     58TODO: to be documented what can go wrong (false credentials etc.).
     59}}}
     60
     61==== Description
     62The {{{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.
     63
     64TODO: is a lock required?
     65
     66
     67=== createlink
     68=== create
     69=== createfolder
     70=== createrelation
     71=== delete
     72=== deleteallversions
     73=== deletefolder
     74=== deletelink
     75=== deleterelation
     76=== detachlifecycle
     77=== disconnect
     78==== Parameters
     79||=**Field** =||=**Value** =||
     80||{{{command}}}    ||{{{disconnect}}}        ||
     81||{{{ticket}}}    ||Session ticket to disconnect.        ||
     82
     83==== Return value
     84The {{{disconnect}}} command returns an XML structure like this:
     85{{{#!xml
     86<success>success.disconnect</success>
     87}}}
     88
     89{{{#!comment
     90TODO: to be documented what can go wrong (error.disconnect?).
     91}}}
     92
     93==== Description
     94The {{{disconnect}}} command ends an existing session, identified by its {{{ticket}}}.
     95
     96=== echo
     97> **NOTE:** echo has no legacy action.
     98=== getacls
     99> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods.
     100=== getconfigentry
     101=== getcontent
     102==== Parameters
     103||=**Field** =||=**Value** =||
     104||{{{command}}}    ||{{{getcontent}}}        ||
     105||{{{id}}}    ||ID of the object whose content is to be retrieved.        ||
     106||{{{ticket}}}    ||Session ticket to disconnect.        ||
     107
     108==== Return value
     109The {{{getcontent}}} command returns a stream with the content of the object. Typically, it is written to a file.
     110
     111{{{#!comment
     112TODO: to be documented what can go wrong (wrong id etc.).
     113}}}
     114
     115==== Description
     116The {{{getcontent}}} retrieves the content of an object identified by its {{{id}}}. {{{getcontent}}} is the only command returning file content instead of an XML structure.
     117
     118
     119=== getfolder
     120=== getfolderbypath
     121==== Parameters
     122||=**Field** =||=**Value** =||
     123||{{{command}}}    ||{{{getfolderbypath}}}        ||
     124||{{{path}}}    ||[wiki:Public/Docs/CinnamonFolderPaths Path] to the folder.        ||
     125||{{{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}}}.       ||
     126||{{{ticket}}}    ||Session ticket.        ||
     127
     128==== Return value
     129The {{{getfolderbypath}}} command returns an [wiki:Public/Docs/CinnamonFolderXml XML representation of the folder] with the given path.
     130
     131{{{#!comment
     132TODO: to be documented what can go wrong (wrong id etc.).
     133}}}
     134
     135
     136
     137=== getfoldermeta
     138=== getfoldersbyid
     139=== getfoldertypes
     140> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods.
     141=== getformats
     142=== getmeta
     143==== Parameters
     144||=**Field** =||=**Value** =||
     145||{{{command}}}    ||{{{getmeta}}}        ||
     146||{{{id}}}    ||ID of the object whose metadata is to be retrieved.        ||
     147||{{{ticket}}}    ||Session ticket.        ||
     148
     149==== Return value
     150The {{{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).
     151
     152{{{#!comment
     153TODO: to be documented what can go wrong (wrong id etc.).
     154}}}
     155
     156
     157
     158=== getmetaset
     159==== Parameters
     160||=**Field** =||=**Value** =||
     161||{{{command}}}    ||{{{getmetaset}}}        ||
     162||{{{id}}}    ||ID of the object whose metadata is to be retrieved.        ||
     163||{{{class_name}}}    ||{{{OSD}}} (**O**bject **S**ystem **D**ata) to retrieve an object metaset, {{{Folder}}} to retrieve a folder metaset.        ||
     164||{{{type_name}}}    ||Name of the metaset type to be retrieved.        ||
     165||{{{ticket}}}    ||Session ticket.        ||
     166
     167==== Return value
     168The {{{getmetaset}}} command returns one metaset of the [wiki:Public/Docs/CinnamonMetadata metadata] of the object or folder with the specified id.
     169
     170{{{#!comment
     171TODO: to be documented what can go wrong (wrong id etc.).
     172}}}
     173
     174
     175
     176=== getobject
     177=== getobjects
     178==== Parameters
     179||=**Field** =||=**Value** =||
     180||{{{command}}}    ||{{{getobjects}}}        ||
     181||{{{parentid}}}    ||ID of the parent folder of the objects to be retrieved.        ||
     182||{{{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}}}.       ||
     183||{{{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.        ||
     184||{{{ticket}}}    ||Session ticket.        ||
     185
     186==== Return value
     187The {{{getobjects}}} command returns the objects inside the given parent folder as an [wiki:Public/Docs/CinnamonObjectXml XML representation].
     188
     189{{{#!comment
     190TODO: to be documented what can go wrong (wrong id etc.).
     191}}}
     192
     193
     194
     195=== getobjectsbyid
     196=== getobjtypes
     197> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods.
     198=== getrelations
     199=== getrelationtypes
     200> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods.
     201=== getsubfolders
     202==== Parameters
     203||=**Field** =||=**Value** =||
     204||{{{command}}}    ||{{{getsubfolders}}}        ||
     205||{{{parentid}}}    ||ID of the parent folder of the subfolders to be retrieved.[[br]]      The value {{{0}}} returns the subfolders of the root folder. ||
     206||{{{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}}}.       ||
     207||{{{ticket}}}    ||Session ticket.        ||
     208
     209==== Return value
     210The {{{getsubfolders}}} command returns the subfolders inside the given parent folder as an [wiki:Public/Docs/CinnamonFolderXml XML representation].
     211
     212{{{#!comment
     213TODO: to be documented what can go wrong (wrong id etc.).
     214}}}
     215
     216
     217=== getusers
     218> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods.
     219=== getuserspermissions
     220=== listaclentries
     221> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods.
     222=== listgroups
     223> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods.
     224=== listindexgroups
     225> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods.
     226=== listindexitems
     227> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods.
     228=== listlanguages
     229> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods.
     230=== listlifecycles
     231> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods.
     232=== listmetasettypes
     233> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods.
     234=== listuilanguages
     235> **NOTE:** This API method will be replaced by a future, global session configuration transfer instead of individual methods.
     236=== lockobject
     237=== renderindexedosd
     238> **NOTE:** New in build 117.
     239=== renderindexedfolder
     240> **NOTE:** New in build 117.
     241=== searchfolders
     242=== searchobjectids
     243=== searchobjects
     244==== Parameters
     245||=**Field** =||=**Value** =||
     246||{{{command}}}    ||{{{searchobjects}}}        ||
     247||{{{ticket}}}    ||Session ticket.        ||
     248||{{{query}}}    ||Native Lucene XML query.        ||
     249||{{{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}}}.       ||
     250||{{{page_size}}}    ||[optional] Maximal number of objects to returned.        ||
     251||{{{page}}}    ||[optional] Zero-based index of the page to return, this parameter may only be set if {{{page_size}}} has also been set.         ||
     252
     253==== Return value
     254The {{{searchobjects}}} command returns an [wiki:Public/Docs/CinnamonObjectXml XML structure] like this:
     255{{{#!xml
     256<objects total-results="15">
     257  <object>
     258    <!-- XML representation of an object -->
     259  </object>
     260  <object>
     261    <!-- XML representation of an object -->
     262  </object>
     263  <!-- 13 more objects -->
     264</objects>
     265}}}
     266
     267{{{#!comment
     268TODO: to be documented what can go wrong .
     269}}}
     270
     271==== Description
     272The {{{searchobjects}}} command executes a search using a Lucene XML query and returns the objects found as an XML structure.
     273
     274=== setchangedstatus
     275=== setcontent
     276=== setmeta
     277=== setmetaset
     278=== setpassword
     279=== setsummary
     280=== setsysmeta
     281=== unlockobject
     282=== updatefolder
     283=== updatelink
     284=== version
     285
     286== Deprecated methods
     287=== checktranslation [deprecated]
     288> **IMPORTANT:** This API method is deprecated and will be removed in a future release without further notice.
     289This method is highly special, can be replaced with other API methods and the render mechanism it supports is deprecated. Some customers still use it.
     290=== createtranslation [deprecated]
     291> **IMPORTANT:** This API method is deprecated and will be removed in a future release without further notice.
     292This method is highly special, can be replaced with other API methods and the render mechanism it supports is deprecated. Some customers still use it.
     293=== forksession  [deprecated]
     294> **IMPORTANT:** This API method is deprecated and will be removed in a future release without further notice.
     295It is no longer used in client libraries and there seems to be no use case.
     296=== getsysmeta  [deprecated]
     297> **IMPORTANT:** This API method is deprecated and will be removed in a future release without further notice.
     298All such data is returned by {{{getobject}}} or other API methods returning objects.=== startrendertask [deprecated]
     299> **IMPORTANT:** This API method is deprecated and will be removed in a future release without further notice.
     300This method is highly special, can be replaced with other API methods and the render mechanism it supports is deprecated. Some customers still use it.
     301=== sudo [deprecated]
     302> **IMPORTANT:** This API method is deprecated and will be removed in a future release without further notice.
     303The entire sudo functionality has become obsolete with the change tracking logic.