Context Navigation

Calenco V2.1 REST API

These are the REST API specifications for Calenco V2.1 Core. It obsoletes both the Actions URL proposal and Alternative Restful URL Schema specifications.

Definitions
1. Notes
2. Possible HTTP Response Codes Summary
3. API Summary
Create Workspace
1. Roles
2. Request
3. Responses
List Workspaces
1. Roles
2. Request
3. Responses
  1. JSON
  2. XML
4. Notes
Change Workspace WKSP Status
1. Roles
2. Request
3. Responses
Backup Workspace WKSP
1. Roles
2. Request
3. Responses
Create Language for Workspace WKSP
1. Roles
2. Request
3. Responses
List Languages for Workspace WKSP
1. Roles
2. Request
3. Response
Change Status for Language LANG of Workspace WKSP
1. Roles
2. Request
3. Responses
Export Content for Workspace WKSP
1. Roles
2. Request
3. Responses
Store File in Language LANG for Workspace WKSP
1. Roles
2. Request
3. Responses
List Files in Language LANG for Workspace WKSP
1. Roles
2. Request
3. Responses
  1. JSON
  2. XML
Update File in Language LANG for Workspace WKSP
1. Roles
2. Request
3. Responses
4. Notes
Retrieve File FNAME of Workspace WKSP
1. Roles
2. Request
3. Responses
Export File FNAME of Workspace WKSP
1. Roles
2. Request
3. Responses
4. Notes
Remove File FNAME from Workspace WKSP
1. Roles
2. Request
3. Responses
4. Notes
Retrieve Metadata for File FNAME of Workspace WKSP
1. Roles
2. Request
3. Response
4. Notes
Allowed Methods for File FNAME of Workspace WKSP
1. Roles
2. Request
3. Response
4. Notes
Lock file FNAME of workspace WKSP
1. Roles
2. Request
3. Response
4. Notes
Unlock file FNAME of workspace WKSP
1. Roles
2. Request
3. Responses
List Properties for File FNAME of Workspace WKSP
1. Roles
2. Request
3. Responses
  1. JSON
  2. XML
Add or Change Property for File FNAME of Workspace WKSP
1. Roles
2. Request
3. Responses
Remove Property PNAME from File FNAME of Workspace WKSP
1. Roles
2. Request
3. Responses
Retrieve Revision History for file FNAME of Workspace WKSP
1. Roles
2. Request
3. Response
Create Publication for Workspace WKSP
1. Roles
2. Request
3. Responses
List Publications for Workspace WKSP
1. Roles
2. Request
3. Responses
  1. JSON
  2. XML
Retrieve Details for Publication PUB of Workspace WKSP
1. Roles
2. Request
3. Responses
  1. JSON
  2. XML
4. Notes
Change Parameters for Publication PUB of Workspace WKSP
1. Roles
2. Request
3. Responses
Remove Publication PUB from Workspace WKSP
1. Roles
2. Request
3. Responses
4. Notes
Queue Publication PUB of Workspace WKSP for Regeneration
1. Roles
2. Request
3. Responses
Retrieve Publication Output OUTPUT for Workspace WKSP
1. Roles
2. Request
3. Responses
Create Classification for Workspace WKSP
1. Roles
2. Request
3. Responses
List Classifications for Workspace WKSP
1. Roles
2. Request
3. Responses
  1. JSON
  2. XML
Retrieve Classification CLASSIF for Workspace WKSP
1. Roles
2. Request
3. Response
4. Notes
Change Classification CLASSIF for Workspace WKSP
1. Roles
2. Request
3. Responses
Classify Files under Classification CLASSIF for Workspace WKSP
1. Roles
2. Request
3. Responses
Remove Classification CLASSIF from Workspace WKSP
1. Roles
2. Request
3. Responses
Create Association on Workspace WKSP
1. Roles
2. Request
3. Responses
List Associations for Workspace WKSP
1. Roles
2. Request
3. Responses
  1. XML
  2. JSON
Retrieve Association ASSOC for Workspace WKSP
1. Roles
2. Request
3. Response
4. Notes
Create Release for Workspace WKSP
1. Roles
2. Request
3. Responses
List Releases for Workspace WKSP
1. Roles
2. Request
3. Response
4. Notes
Remove Release REL from Workspace WKSP
1. Roles
2. Request
3. Responses
4. Notes
Retrieve File FNAME from Release REL for Workspace WKSP
1. Roles
2. Request
3. Responses
4. Notes
List Stylesheets for Workspace WKSP
1. Roles
2. Request
3. Response
4. Notes
Retrieve File Dependencies Tree for Workspace WKSP
1. Roles
2. Request
3. Response
Retrieve File List for Workspace WKSP
1. Roles
2. Request
3. Response
List Available Toolchains
1. Roles
2. Request
3. Responses
  1. JSON
  2. XML
Retrieve Toolchain TCHAIN Details
1. Roles
2. Request
3. Response
4. Notes
Retrieve File of Kind KIND for the AddOn ADDON
1. Roles
2. Request
3. Responses
List Available Languages
1. Roles
2. Request
3. Responses
  1. JSON
  2. XML
4. Notes
Create Calenco User
1. Roles
2. Request
3. Responses
List Calenco Users
1. Roles
2. Request
3. Responses
  1. JSON
  2. XML
Retrieve Details for Calenco User USER
1. Roles
2. Request
3. Response
Change Parameters for Calenco User USER
1. Roles
2. Request
3. Responses
List Access Rights for Calenco User USER
1. Roles
2. Request
3. Response
Grant Access Rights for Calenco User USER
1. Roles
2. Request
3. Responses
Revoke Access Rights for Calenco User USER
1. Roles
2. Request
3. Responses
Retrieve System Information
1. Roles
2. Request
3. Response
Files Naming

Definitions

Notes

All URIs are relative to a base Calenco URL, for example: https://calenco.com
User roles are encoded as follows:
- R : Regular (unprivileged) User
- A : Workspace Administrator
- S : Calenco System Administrator
Users with role S have unrestricted access to any part of the system, even if they are not explicitly listed in the Roles requirement for the requests
All URIs require authentication. HTTP Basic authentication is used (over an encrypted SSL tunnel - HTTPS)
All data expected by POST/PUT is to be provided in application/x-www-form-urlencoded format, a.k.a. standard web forms. Files to be uploaded are to be provided in multipart/form-data format, a.k.a. standard HTML form's "file" input
The default media type returned in the response, or expected by the request handler, is specified in the Media Type column in the API Summary table. If you specify a non-supported media type (for example: Accept: application/xml on a resource that doesn't provide an XML representation), the default representation and media type for the requested resource is returned in the response
XML and JSON representations of responses are written using whitespace to facilitate their reading. Do not count on that as the "exact" representation format (for example, to parse the response). Use adecuated libraries for your client programming. Check the JSON website for JSON libraries for many programming languages. There's also free and open source XML libraries for many programming langauges available on the web, and even some programming languages (Java for example) have XML libraries already included as part of their standard distributions

Possible HTTP Response Codes Summary

If specific HTTP response codes are not specified for the API, you can use the table below as a general rule to understand the meaning of the response:

HTTP Response Code	Meaning
200 (OK)	The operation was successful
201 (Created)	Resource creation (POST) was successful
202 (Accepted)	Resource queuing (POST) was successful
204 (No Content)	Resource was successfuly removed (DELETE), or the response for the request doesn't need (or cannot have) an entity body
400 (Bad Request)	Wrong/bad parameters were provided, or required parameters are missing
401 (Authorization Required)	Credentials must be provided to access the requested resource
403 (Forbidden)	The provided credentials are not sufficient to perform the desired request, or a non-active resource is being requested
404 (Not Found)	A non-existing resource is being requested
409 (Conflict)	The operation can result in bad state, or conflicting resources
500 (Internal Server Error)	The operation failed due to some server processing problem (I/O, JCR, other exceptions)

API Summary

Specification	Request	Media Type
Create Workspace	`POST /workspaces`	`application/x-www-form-urlencoded`
List Workspaces	`GET /workspaces`	`application/json`
Change Workspace WKSP Status	`PUT /workspaces/WKSP`	`application/x-www-form-urlencoded`
Backup Workspace WKSP	`GET /workspaces/WKSP`	`application/zip`
Create Language for Workspace WKSP	`POST /workspaces/WKSP/languages`	`application/x-www-form-urlencoded`
List Languages for Workspace WKSP	`GET /workspaces/WKSP/languages`	`application/json`
Change Status for Language LANG of Workspace WKSP	`PUT /workspaces/WKSP/languages/LANG`	`application/x-www-form-urlencoded`
Export Content for Workspace WKSP	`GET /workspaces/WKSP/content`	`application/zip`
Store File in Language LANG for Workspace WKSP	`POST /workspaces/WKSP/content/LANG`	`multipart/form-data`
List Files in Language LANG for Workspace WKSP	`GET /workspaces/WKSP/content/LANG`	`application/json`
Update File in Language LANG for Workspace WKSP	`PUT /workspaces/WKSP/content/LANG`	`Binary Stream`
Retrieve File FNAME of Workspace WKSP	`GET /workspaces/WKSP/content/FNAME`	`Binary Stream`
Export File FNAME of Workspace WKSP	`GET /workspaces/WKSP/content/FNAME`	`application/zip`
Remove File FNAME from Workspace WKSP	`DELETE /workspaces/WKSP/content/FNAME`
Retrieve Metadata for File FNAME of Workspace WKSP	`HEAD /workspaces/WKSP/content/FNAME`
Allowed Methods for File FNAME of Workspace WKSP	`OPTIONS /workspaces/WKSP/content/FNAME`
Lock file FNAME of workspace WKSP	`LOCK /workspaces/WKSP/content/FNAME`	application/xml
Unlock file FNAME of workspace WKSP	`UNLOCK /workspaces/WKSP/content/FNAME`
List Properties for File FNAME of Workspace WKSP	`GET /workspaces/WKSP/content/FNAME/properties`	`application/json`
Add or Change Property for File FNAME of Workspace WKSP	`PUT /workspaces/WKSP/content/FNAME/properties/PNAME`	`application/x-www-form-urlencoded`
Remove Property PNAME from File FNAME of Workspace WKSP	`DELETE /workspaces/WKSP/content/FNAME/properties/PNAME`
Retrieve Revision History for file FNAME of Workspace WKSP	`GET /workspaces/WKSP/content/FNAME/revhistory`	`application/json`
Create Publication for Workspace WKSP	`POST /workspaces/WKSP/publications`	`application/x-www-form-urlencoded`
List Publications for Workspace WKSP	`GET /workspaces/WKSP/publications`	`application/json`
Retrieve Details for Publication PUB of Workspace WKSP	`GET /workspaces/WKSP/publications/PUB`	`application/json`
Change Parameters for Publication PUB of Workspace WKSP	`PUT /workspaces/WKSP/publications/PUB`	`application/x-www-form-urlencoded`
Remove Publication PUB from Workspace WKSP	`DELETE /workspaces/WKSP/publications/PUB`
Queue Publication PUB of Workspace WKSP for Regeneration	`POST /workspaces/WKSP/pubsqueue`	`application/x-www-form-urlencoded`
Retrieve Publication Output OUTPUT for Workspace WKSP	`GET /workspaces/WKSP/outputs/OUTPUT`	`Binary Stream`
Create Classification for Workspace WKSP	`POST /workspaces/WKSP/classifications`	`application/x-www-form-urlencoded`
List Classifications for Workspace WKSP	`GET /workspaces/WKSP/classifications`	`application/json`
Retrieve Classification CLASSIF for Workspace WKSP	`GET /workspaces/WKSP/classifications/CLASSIF`	`text/xml`
Change Classification CLASSIF for Workspace WKSP	`POST /workspaces/WKSP/classifications/CLASSIF`	`application/x-www-form-urlencoded`
Classify Files under Classification CLASSIF for Workspace WKSP	`PUT /workspaces/WKSP/classifications/CLASSIF`	`application/json`
Remove Classification CLASSIF from Workspace WKSP	`DELETE /workspaces/WKSP/classifications/CLASSIF`
Create Association on Workspace WKSP	`POST /workspaces/WKSP/associations`	`application/x-www-form-urlencoded`
List Associations for Workspace WKSP	`GET /workspaces/WKSP/associations`	`text/xml`
Retrieve Association ASSOC for Workspace WKSP	`GET /workspaces/WKSP/associations/ASSOC`	`text/xml`
Create Release for Workspace WKSP	`POST /workspaces/WKSP/releases`	`application/x-www-form-urlencoded`
List Releases for Workspace WKSP	`GET /workspaces/WKSP/releases`	`text/xml`
Remove Release REL from Workspace WKSP	`DELETE /workspaces/WKSP/releases/REL`
Retrieve File FNAME from Release REL for Workspace WKSP	`GET /workspaces/WKSP/releases/REL/FNAME`	`Binary Stream`
List Stylesheets for Workspace WKSP	`GET /workspaces/WKSP/stylesheets`	`application/json`
Retrieve File Dependencies Tree for Workspace WKSP	`GET /workspaces/WKSP/depstree`	`application/json`
Retrieve File List for Workspace WKSP	`GET /workspaces/WKSP/filelist`	`application/json`
List Available Toolchains	`GET /system/toolchains`	`application/json`
Retrieve Toolchain TCHAIN Details	`GET /system/toolchains/TCHAIN`	`text/xml`
Retrieve File of Kind KIND for the AddOn ADDON	`GET /system/addons/ADDON/KIND`	`Binary Stream`
List Available Languages	`GET /system/languages`	`application/json`
Create Calenco User	`POST /system/users`	`application/x-www-form-urlencoded`
List Calenco Users	`GET /system/users`	`application/json`
Retrieve Details for Calenco User USER	`GET /system/users/USER`	`application/json`
Change Parameters for Calenco User USER	`PUT /system/users/USER`	`application/x-www-form-urlencoded`
List Access Rights for Calenco User USER	`GET /system/usersrights/USER`	`application/json`
Grant Access Rights for Calenco User USER	`PUT /system/usersrights/USER`	`application/x-www-form-urlencoded`
Revoke Access Rights for Calenco User USER	`DELETE /system/usersrights/USER`
Retrieve System Information	`GET /system/info`	`application/json`

Create Workspace

Roles

Request

POST /workspaces

Field	Description	Notes
description	A descriptive name for the workspace, for example: NeoDoc, Impika, Canonical, TIL Technologies	The workspace name must start with a letter. Even if there's no restriction on the allowed characters, it's safer to use only the English alphabet letters, numbers, the minus sign, the underscore, and the space character

Responses

HTTP Response Code	Meaning
201	The workspace was created and marked active (enabled)
400	Required parameter "description" is missing, or empty
403	You don't have system administrator rights
409	A workspace with that name already exists

List Workspaces

Roles

Request

GET /workspaces

Responses

JSON

{
  count:2,
  items:
  [
    {
      name:"W1",
      active:true,
      href:"/workspaces/W1"
    },
    {
      name:"W2",
      active:false,
      href:"/workspaces/W2"
    }
  ]
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<workspaces>
  <workspace active="true" href="/workspaces/W1">W1</workspace>
  <workspace active="false" href="/workspaces/W2">W2</workspace>
</workspaces>

Notes

If the user has role S, all workspaces are listed. If the user has roles A or R, only the workspaces he has access to are listed.

Change Workspace WKSP Status

Roles

Request

PUT /workspaces/WKSP

Field	Possible Values	Description
active	true, false	Whether workspace WKSP is to be marked active or not. Any non-empty value other than "true" is considered as if "false" was specified

Responses

HTTP Response Code	Meaning
200	The status of workspace WKSP has been changed
400	Required parameter "active" is missing, or empty
403	You don't have system administrator rights
404	Workspace WKSP doesn't exist

Backup Workspace WKSP

Roles

Request

GET /workspaces/WKSP
Accept: application/zip

Responses

HTTP Response Code	Meaning
200	The compressed (ZIP) backup file of workspace WKSP is streamed to the client
403	You don't have workspace administrator rights for workspace WKSP
404	Workspace WKSP doesn't exist

Create Language for Workspace WKSP

Roles

Request

POST /workspaces/WKSP/languages

Field	Possible Values	Description
lang	Constrained from the list of available system languages. See List Available Languages	The IETF code of the language to create, for example: en, fr_FR, etc.

Responses

HTTP Response Code	Meaning
201	The given language is associated with workspace WKSP, marked active, and the proper storage structure is created to work with files in that language
400	Required parameter "lang" is missing, empty, or it points to a langauge that's not available (either not supported by the system, or simply 'bogus', for example lang=zz)
403	You don't have workspace administrator rights for workspace WKSP
404	Workspace WKSP doesn't exist

List Languages for Workspace WKSP

Roles

Request

GET /workspaces/WKSP/languages

Response

{
  count:3,
  label:"name",
  identifier:"code",
  items:
  [
    {
      name:"English",
      active:true,
      code:"en"
    },
    {
      name:"Français",
      active:true,
      code:"fr"
    },
    {
      name:"International",
      active:true,
      code:"INTL"
    }
  ]
}

Change Status for Language LANG of Workspace WKSP

Roles

Request

PUT /workspaces/WKSP/languages/LANG

Field	Possible Values	Description
active	true, false	Whether language LANG of workspace WKSP is to be marked active or not. Any non-empty value other than "true" is considered as if "false" was specified

Responses

HTTP Response Code	Meaning
200	The status of language LANG of workspace WKSP has been changed
400	Required parameter "active" is missing, or empty
403	You don't have workspace administrator rights for workspace WKSP
404	Workspace WKSP doesn't exist, or language LANG is not created on workspace WKSP

Export Content for Workspace WKSP

Roles

Request

GET /workspaces/WKSP/content
Accept: application/zip

Responses

HTTP Response Code	Meaning
200	A compressed (ZIP) file with all content (files and folders) of workspace WKSP is streamed to the client
403	You don't have rights to access workspace WKSP
404	Workspace WKSP doesn't exist

Store File in Language LANG for Workspace WKSP

Roles

Request

POST /workspaces/WKSP/content/LANG

If LANG is empty (missing), the file is stored in the International (common to all languages) folder.

Field	Description	Notes
file	The file to store (upload)
cname	Optional. The name of the classification to classify the stored file under	If `cname` doesn't point to an existing classification, it's "Attic", or it's ommited, it's as if "All Files" (`ALL_FILES`) has been specified

Responses

HTTP Response Code	Meaning
200	The file was stored fine
403	You don't have rights to access workspace WKSP, or LANG is not active on workspace WKSP
404	Workspace WKSP doesn't exist

List Files in Language LANG for Workspace WKSP

Roles

Request

GET /workspaces/WKSP/content/LANG

Responses

The examples below assume that LANG was empty, meaning list international (common to all languages) files. If LANG is not empty, the files for the given language are listed and there will be no folder entries, only file entries.

JSON

{
  label:"name",
  items:
  [
    {
      parentDir:"",
      directory:true,
      name:"en",
      path:"/workspaces/WKSP/content/en",
      children:[],
      type:"folder"
    },
    {
      parentDir:"",
      rev:"1.0",
      name:"Samba1.xml",
      path:"/workspaces/WSKP/content/Samba1.xml",
      type:"text/xml",
      size:1643},
    {
      parentDir:"",
      rev:"1.2",
      name:"Samba2.xml",
      path:"/workspaces/WKSP/content/Samba2.xml",
      type:"text/xml",
      size:6001
    },
    {
      parentDir:"",
      rev:"1.0",
      name:"Samba3.xml",
      path:"/workspaces/WKSP/content/Samba3.xml",
      type:"text/xml",
      size:1995
    }
  ]
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<dir>
  <entry class="folder" href="/workspaces/WKSP/content/en">en</entry>
  <entry class="file" href="/workspaces/WKSP/content/Samba1.xml" rev="1.0" type="text-xml">Samba1.xml</entry>
  <entry class="file" href="/workspaces/WKSP/content/Samba2.xml" rev="1.2" type="text-xml">Samba2.xml</entry>
  <entry class="file" href="/workspaces/WKSP/content/Samba3.xml" rev="1.0" type="text-xml">Samba3.xml</entry>
</dir>

Update File in Language LANG for Workspace WKSP

Roles

Request

PUT /workspaces/WKSP/content/FNAME

The entity body of the request has the binary data for the file

See Files Naming

Responses

HTTP Response Code	Meaning
201	The file was stored fine
403	You don't have rights to access workspace WKSP, or the language part of FNAME points to a language that is not active on workspace WKSP
404	Workspace WKSP doesn't exist

Notes

This request is used by WebDAV clients to store files also, not only to update files (thus files stored this way end up in the "All Files" classification, because the WebDAV clients don't specify the classification name)

Retrieve File FNAME of Workspace WKSP

Roles

Request

GET /workspaces/WKSP/content/FNAME?rev=R

Query Parameter	Description	Possible Values	Notes
rev	The revision of file FNAME of workspace WKSP to obtain	1.0, 1.1, 1.357	Optional. If not specified, obtain the latest (HEAD) revision

See Files Naming

Responses

HTTP Response Code	Meaning
200	The file is streamed to the client
403	You don't have rights to access workspace WKSP, or the language part of FNAME points to a language that is not active on workspace WKSP
404	File FNAME (optionally, at revision R) doesn't exist

Export File FNAME of Workspace WKSP

Roles

Request

GET /workspaces/WKSP/content/FNAME
Accept: application/zip

See Files Naming

Responses

HTTP Response Code	Meaning
200	A compressed archive (ZIP) containing FNAME for workspace WKSP and all its dependencies is streamed to the client
403	You don't have rights to access workspace WKSP, or the language part of FNAME points to a language that is not active on workspace WKSP
404	File FNAME (optionally, at revision R) doesn't exist

Notes

"all its dependencies" mean all dependencies stored in the content repository, external (for example: http://my.server.com/imgs/myimage.png) dependencies are not contained in the response
All files are exported at their latest (HEAD) revisions

Remove File FNAME from Workspace WKSP

Roles

Request

DELETE /workspaces/WKSP/content/FNAME

Responses

HTTP Response Code	Meaning
204	The file was deleted from the content repository
400	The language part of FNAME points to a language that is not active on workspace WKSP
403	You don't have rights to access workspace WKSP
404	File FNAME doesn't exist

Notes

There is no relationships (dependencies, other associations) checking of any kind, the file is just deleted from the content repository

Retrieve Metadata for File FNAME of Workspace WKSP

Roles

Request

HEAD /workspaces/WKSP/content/FNAME

Response

HTTP/1.1 200 OK
Content-Length: 1643
Content-Type: text/xml
Last-Modified: Fri, 16 Jul 2010 17:41:05 GMT

Notes

This request is used by WebDAV clients

Allowed Methods for File FNAME of Workspace WKSP

Roles

Request

OPTIONS /workspaces/WKSP/content/FNAME

Response

HTTP/1.1 200 OK
Connection: close
Date: Mon, 19 Jul 2010 13:58:33 GMT
Accept-Ranges: bytes
Allow: OPTIONS, PROPFIND, GET, POST, PUT, DELETE, HEAD, LOCK, UNLOCK
Server: Restlet-Framework/2.0
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
DAV: 1
MS-Author-Via: DAV
Content-Length: 1
Content-Type: text/plain; charset=UTF-8

Notes

This request is used by WebDAV clients

Lock file FNAME of workspace WKSP

Roles

Request

LOCK /workspaces/WKSP/content/FNAME
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<d:lockinfo xmlns:d="DAV:">
  <d:lockscope>
    <d:exclusive/>
  </d:lockscope>
  <d:locktype>
    <d:write/>
  </d:locktype>
  <d:owner>USER</d:owner>
</d:lockinfo>

Response

<?xml version="1.0" encoding="UTF-8"?>
<d:prop xmlns:d="DAV:">
    <d:lockdiscovery>
        <d:activelock>
            <d:lockscope>
                <d:exclusive />
            </d:lockscope>
            <d:locktype>
                <d:write />
            </d:locktype>
            <d:depth>0</d:depth>
            <d:owner>USER</d:owner>
            <d:timeout>Second-31536000</d:timeout>
            <d:locktoken>
                <d:href>opaquelocktoken:a14e4f69-713d-4228-8a1c-a9412a572756</d:href>
            </d:locktoken>
            <d:lockroot>
                <d:href>http://calenco.server/workspaces/WKSP/content/FNAME</d:href>
            </d:lockroot>
        </d:activelock>
    </d:lockdiscovery>
</d:prop>

Notes

This request is used by WebDAV clients. The implementation differs from WebDAV specs: the lock owner is the authenticated user instead of the given value for the <d:owner> element in the request body.

Unlock file FNAME of workspace WKSP

Roles

Request

UNLOCK /workspaces/WKSP/content/FNAME

DAV Request Header	Meaning	Example
Lock-Token	The token for the lock. If the user is not an administrator, this value must match the one in the lock or else FNAME will not be unlocked	`Lock-Token: <opaquelocktoken:a14e4f69-713d-4228-8a1c-a9412a572756>`

Responses

HTTP Response Code	Meaning
204	FNAME was successfuly unlocked
400	Lock-Token is missing, or empty
403	You are neither the lock owner, nor an administrator, or the provided token doesn't match the lock
404	FNAME of workspace WKSP doesn't exist
409	FNAME of workspace WKSP wasn't locked

List Properties for File FNAME of Workspace WKSP

Roles

Request

GET /workspaces/WKSP/content/FNAME/properties?pat=PATTERN

Query Parameter	Description	Possible Values	Notes
pat	A string describing the pattern to match property names	"", "", "cco_", "myprop_*", ...	Optional. If not specified, it's the same as specifying "*" (get all properties). Calenco-specific property names start with "cco_", for example "cco_size" for a file's size, in bytes

Responses

JSON

{
  pattern:"*",
  file:"/Samba1.xml",
  count:8,
  items:
  [
    {
      name:"cco_xmlwellformed",
      value:"true",
      type:"string"
    },
    {
      name:"cco_size",
      value:"1643",
      type:"long"
    },
    {
      name:"cco_xmltype",
      value:"DocBook5.0",
      type:"string"
    },
    {
      name:"jcr:mixinTypes",
      value:"mix:lockable",
      type:"name"
    },
    {
      name:"cco_xmlvalid",
      value:"true",
      type:"string"
    },
    {
      name:"cco_authoremail",
      value:"admin@calenco.com",
      type:"string"
    },
    {
      name:"jcr:primaryType",
      value:"nt:unstructured",
      type:"name"
    },
    {
      name:"cco_author",
      value:"System Administrator",
      type:"string"
    }
  ]
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<properties count="8" file="/Samba1.xml" pattern="*">
  <property name="cco_xmlwellformed" type="string">true</property>
  <property name="cco_size" type="long">1643</property>
  <property name="cco_xmltype" type="string">DocBook5.0</property>
  <property name="jcr:mixinTypes" type="name">mix:lockable</property>
  <property name="cco_xmlvalid" type="string">true</property>
  <property name="cco_authoremail" type="string">admin@calenco.com</property>
  <property name="jcr:primaryType" type="name">nt:unstructured</property>
  <property name="cco_author" type="string">System Administrator</property>
</properties>

Add or Change Property for File FNAME of Workspace WKSP

Roles

Request

PUT /workspaces/WKSP/content/FNAME/properties/PNAME

Field	Description	Notes
value	Value for the property	Please note that all properties are single-valued. To specify multiple-valued properties a client-defined separator has to be used to separate different values

Responses

HTTP Response Code	Meaning
200	Property PNAME of file FNAME of workspace WKSP is added or changed
400	Required parameter "value" is missing, or empty
403	You don't have rights to access workspace WKSP
404	File FNAME doesn't exist, or the language part of FNAME points to a language that is not active on workspace WKSP

Remove Property PNAME from File FNAME of Workspace WKSP

Roles

Request

DELETE /workspaces/WKSP/content/FNAME/properties/PNAME

Responses

HTTP Response Code	Meaning
204	Property PNAME of file FNAME of workspace WKSP is removed
403	You don't have rights to access workspace WKSP
404	Property PNAME is not defined, or ile FNAME doesn't exist, or the language part of FNAME points to a language that is not active on workspace WKSP

Retrieve Revision History for file FNAME of Workspace WKSP

Roles

Request

GET /workspaces/WKSP/content/FNAME/revhistory

Response

{
  count:3,
  revisions:
  [
    {
      author:"Peter Pingus",
      rev:"1.2",
      name:"Samba2.xml",
      date:"2010-07-16 14:41:58",
      href:"/workspaces/WKSP/content/Samba2.xml?rev=1.2"
    },
    {
      author:"System Administrator",
      rev:"1.1",
      name:"Samba2.xml",
      date:"2010-07-13 13:10:53",
      href:"/workspaces/WKSP/content/Samba2.xml?rev=1.1"
    },
    {
      author:"Peter Pingus",
      rev:"1.0",
      name:"Samba2.xml",
      date:"2010-07-10 10:30:08",
      href:"/workspaces/WKSP/content/Samba2.xml?rev=1.0"
    }
  ]
}

Create Publication for Workspace WKSP

Roles

Request

POST /workspaces/WKSP/publications

Field	Description	Possible Values	Notes
name	The name of the publication	String (My Publication, P1, Samba PDF A4, ...)
input	The file to publish	URI, example : /workspaces/WKSP/content/en/Master-Starter.xml	See Files Naming
outname	File name of compiled output, minus the extension	String (Java-UG-HIRES, Samba_PDF_A4)	If output is not self-contained (for example HTML), this will be the name of the folder containing output files
toolchain	The toolchain to use	String (DocBook5_to_PDF, DITA_to_XHTML, ...)
xsl	The XSL to use	URI	See Files Naming
automatic	Whether this publication should be automatically updated (republished) when one of its dependencies change	true, false	Optional. Any non-empty value that's not "true" is assumed to be "false". False by default.
tparams	Multiple-value list of the toolchain params	images.dpi=300;do.xincludes=yes	Optional
xslparams	Multiple-value list of the XSL params	paper.type=A4	Optional
method	Where to store the publication output: inside the workspace as a file, through WebDAV, or on an FTP server	file, dav, ftp	Optional. If not specified, 'file' (store it inside the workspace) is assumed
rs-user	User name to authenticate on the remote server	ServerUserName
rs-pass	Password to authenticate on the remote server	ServerPassword
rs-host	The remote server name	my.server.com
rs-port	The remote server port to connect to	80, 21, 8080, 65000	If ommited, the default port for the requested service is used
rs-path	The folder on the remote server where to store the publication result	/mypubs/pub1

Responses

HTTP Response Code	Meaning
201	Publication is created and queued to be published
400	Required parameters missing, empty, or have bad values (for example input doesn't point to an existing file in the workspace)
403	You don't have rights to access, or you are not a workspace administrator of, workspace WKSP
409	This workspace has already defined a publication with the given name

List Publications for Workspace WKSP

Roles

Request

GET /workspaces/WKSP/publications

Responses

JSON

{
  count: 1,
  publications:
  [
    {
      xsl: {"href":"DEFAULT"},
      input: {
        type:"DocBook5.0",
        href:"/workspaces/WKSP/content/Samba1.xml"
      },
      status:"success",
      automatic:"false",
      name:"P1",
      output: {
        zip:"true",
        method:"file",
        href:"/workspaces/WKSP/outputs/Samba2.pdf"
      },
      href:"/workspaces/WKSP/publications/P1",
      toolchain: {
        name:"DocBook5_to_PDF"
      }
    }
  ]
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<publications count="1">
  <publication automatic="false" href="/workspaces/WKSP/publications/P1" name="P1" status="success">
    <input href="/workspaces/WKSP/content/Samba1.xml" input-type="DocBook5.0"/>
    <xsl href="DEFAULT"/>
    <toolchain name="DocBook5_to_PDF"/>
    <output href="/workspaces/WKSP/outputs/Samba2.pdf" method="file" zip="true"/>
  </publication>
</publications>

Retrieve Details for Publication PUB of Workspace WKSP

Roles

Request

GET /workspaces/WKSP/publications/PUB

Responses

JSON

{
  xsl: {href:"DEFAULT"},
  input: {
    type:"DocBook5.0",
    href:"/workspaces/WKSP/content/Samba1.xml"
  },
  status:"success",
  automatic:"false",
  name:"P1",
  output: {
    zip:"true",
    method:"file",
    href:"/workspaces/WKSP/outputs/Samba2.pdf"
  },
  href:"/workspaces/WKSP/publications/P1",
  toolchain: {
    name:"DocBook5_to_PDF"
  }
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<publication automatic="false" href="/workspaces/WKSP/publications/P1" name="P1" status="success">
  <input href="/workspaces/WKSP/content/Samba1.xml" input-type="DocBook5.0"/>
  <xsl href="DEFAULT"/><toolchain name="DocBook5_to_PDF"/>
  <output href="/workspaces/WKSP/outputs/Samba2.pdf" method="file" zip="true"/>
</publication>

Notes

Possible values for the status attribute are as follows

Value	Meaning
queued	The publication is waiting in the queue. Output may be available, but it will be an old one
in-progress	The publication is currently being published. Output may be available, but it will be an old one
success	The publication has been published successfuly. Output is available, and is the recently compiled publication
broken	An error happened processing the publication. Output may be available, but it will an old one
unknown	Cannot determinate status. This is very rare, it only happens when there's an error reading the pub's status. Needed for completness

Change Parameters for Publication PUB of Workspace WKSP

Roles

Request

PUT /workspaces/WKSP/publications/PUB

Field	Description	Possible Values	Notes
outname	File name of compiled output, minus the extension	String (Java-UG-HIRES, Samba_PDF_A4)	If output is not self-contained (for example HTML), this will be the name of the folder containing output files
xsl	The XSL to use	URI	See Files Naming
automatic	Whether this publication should be automatically updated (republished) when one of its dependencies change	true, false	Optional. Any non-empty value that's not "true" is assumed to be "false". False by default.
tparams	Multiple-value list of the toolchain params	images.dpi=300;do.xincludes=yes	Optional
xslparams	Multiple-value list of the XSL params	paper.type=A4	Optional
method	Where to store the publication output: inside the workspace as a file, through WebDAV, or on an FTP server	file, dav, ftp	Optional. If not specified, 'file' (store it inside the workspace) is assumed
rs-user	User name to authenticate on the remote server	ServerUserName
rs-pass	Password to authenticate on the remote server	ServerPassword
rs-host	The remote server name	my.server.com
rs-port	The remote server port to connect to	80, 21, 8080, 65000	If ommited, the default port for the requested service is used
rs-path	The folder on the remote server where to store the publication result	/mypubs/pub1

Responses

HTTP Response Code	Meaning
200	Publication paraemters are updated, and the publication is queued to be published
400	Required parameters missing, empty, or have bad values
403	You don't have rights to access, or you are not a workspace administrator of, workspace WKSP
404	Workspace WKSP doesn't have defined a publication named PUB

Remove Publication PUB from Workspace WKSP

Roles

Request

DELETE /workspaces/WKSP/publications/PUB

Responses

HTTP Response Code	Meaning
204	Publication PUB is removed from workspace WKSP
403	You don't have rights to access, or you are not a workspace administrator of, workspace WKSP
404	Workspace WKSP doesn't have defined a publication named PUB

Notes

TODO: Define what happens with output for this publication. If they are stored locally, they should be removed...

Queue Publication PUB of Workspace WKSP for Regeneration

Roles

Request

POST /workspaces/WKSP/pubsqueue

Field	Possible values	Description
name	P1, MyPublication, Java User Guide	The publication's name

Responses

HTTP Response Code	Meaning
202	The given publication is re-queued to be published
400	Required parameter "name" is missing, or empty
403	You don't have rights to access, or you are not a workspace administrator of, workspace WKSP
404	The given publication doesn't exist on workspace WKSP

Retrieve Publication Output OUTPUT for Workspace WKSP

Roles

Request

GET /workspaces/WKSP/outputs/OUTPUT

Responses

HTTP Response Code	Meaning
200	The named OUTPUT file is streamed to the client
403	You don't have rights to access workspace WKSP
404	Publication output OUTPUT doesn't exist on workspace WKSP

Create Classification for Workspace WKSP

Roles

Request

POST /workspaces/WKSP/classifications

Field	Description	Examples	Notes
name	The name of the classification	My Project, By Geolocation, By Language
parent	Optional. The name of the parent classification	By Product	If this parameter is ommited, or it's empty, it means the parent is "All Classifications", that is, it has no specific parent

Responses

HTTP Response Code	Meaning
201	The named classification is created, and available to be used with associations to create ontologies
400	Required parameter "name" is missing, or empty
403	You don't have rights to access workspace WKSP

List Classifications for Workspace WKSP

Roles

Request

GET /workspaces/WKSP/classifications

Responses

JSON

{
  label:"name",
  items: [
    {
      name:"All Files",
      allfiles:true,
      type:"classif",
      href:"/workspaces/WKSP/classifications/ALL_FILES"
    },
    {
      name:"Attic",
      type:"classif",
      href:"/workspaces/WKSP/classifications/Attic"
    },
    {
      directory:true,
      name:"C1",
      type:"classif",
      href:"/workspaces/WKSP/classifications/C1",
      children: [
        {
          name:"C1.1",
          type:"classif",
          href:"/workspaces/WKSP/classifications/C1.1"
        }
      ]
    },
    {
      name:"C2",
      type:"classif",
      href:"/workspaces/WKSP/classifications/C2"
    }
  ]
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<classifications count="4">
  <classification href="/workspaces/WKSP/classifications/Attic" name="Attic"/>
  <classification href="/workspaces/WKSP/classifications/C1" name="C1"/>
  <classification href="/workspaces/WKSP/classifications/C1.1" name="C1.1"/>
  <classification href="/workspaces/WKSP/classifications/C2" name="C2"/>
</classifications>

Retrieve Classification CLASSIF for Workspace WKSP

Roles

Request

GET /workspaces/WKSP/classifications/CLASSIF

Response

<?xml version="1.0" encoding="UTF-8"?>
<classification href="/workspaces/WKSP/classifications/CLASSIF" name="CLASSIF"/>

Notes

This API seems to be barely used, if at all. Deprecate?

Change Classification CLASSIF for Workspace WKSP

Roles

Request

POST /workspaces/WKSP/classifications/CLASSIFICATION

Field	Description	Examples
name	The new name of the classification	By Product, C1, By Technology

Responses

HTTP Response Code	Meaning
201	Classification CLASSIFICATION has been renamed to the given name
400	Required parameter "name" is missing, or empty
403	You don't have rights to access workspace WKSP
404	Classification CLASSIFICATION doesn't exist for workspace WKSP
409	The new name is the same as the old one, or you attempted to change the name of a system-reserved ("All Files", "Attic") classification

Classify Files under Classification CLASSIF for Workspace WKSP

Roles

Request

PUT /workspaces/WKSP/classifications/CLASSIFICATION

Field	Description	Examples
files	A JSON array with the URIs of the files to include in the given classification	["/workspaces/WKSP/content/logo.png", "/workspaces/WKSP/content/en_US/intro.xml"]

Responses

HTTP Response Code	Meaning
200	The given files have been added to classification CLASSIFICATION for workspace WKSP
400	Required parameter "files" is missing, or doesn't have a valid JSON array
403	You don't have rights to access workspace WKSP
404	Classification CLASSIFICATION doesn't exist for workspace WKSP
409	You attempted to (re)classify files under the system-reserved classification "All Files"

Remove Classification CLASSIF from Workspace WKSP

Roles

Request

DELETE /workspaces/WKSP/classifications/CLASSIFICATION

HTTP Custom Request Header	Description	Value	Examples
X-Calenco-Filelist	Instead of removing classification CLASSIFICATION itself, remove the given files from classification CLASSIFICATION	A JSON array with the URIs of the files to remove from classification CLASSIFICATION	["/workspaces/WKSP/content/logo.png", "/workspaces/WKSP/content/en_US/intro.xml"]

Responses

HTTP Request Header Present	CLASSIFICATION	HTTP Response Code	Action
Yes	"Attic"	204	Files are recovered from the Attic and available under the "All Files" classification to be used again
Yes	Not "Attic"	204	Files are removed from CLASSIFICATION
No	"Attic" or "ALL_FILES"	400	You attempted to remove a system-reserved ("All Files", "Attic") classification
No	Nor "Attic", neither "ALL_FILES"	204	CLASSIFICATION is deleted (and also all associations referring to it)

Create Association on Workspace WKSP

Roles

Request

POST /workspaces/WKSP/associations

Field	Possible values	Description	Notes
from	/workspaces/WKSP/content/en/userguide.xml	The origin of the association	It can be a file, file+xpointer, or a comment
to	/system/users/camille	The target of the association	It can be a file, a user, a classification, or workflow
kind	hasAuthor, hasComment, currentTaskIs, hasDepCalled, currentTaskOwnerIs, isSortedAs, isTranslationOf, isClassifiedOnto, subClassOf	The kind of association (relationship) between origin and target

Responses

HTTP Response Code	Meaning
201	Association has been created on workspace WKSP
400	Required parameters missing, or empty
404	Either association end (origin, target) points to a non-existing item in the content repository

List Associations for Workspace WKSP

Roles

Request

GET /workspaces/WKSP/associations/ASSOC

Responses

XML

<?xml version="1.0" encoding="UTF-8">
<associations count="9">
  <association
    href="/workspaces/WKSP/associations/A2182767000a0f12ac7d13c3bec015ee2"
    from="/workspaces/WKSP/classifications/C1.1"
    kind="isSubclassOf"
    to="/workspaces/WKSP/classifications/C1"
  />
  <association
    href="/workspaces/WKSP/associations/A313e1a17a550665da2edd5e7b90f164c"
    from="/workspaces/WKSP/content/Samba2.xml?rev=1.0"
    kind="hasAuthor"
    to="/system/users/admin@calenco.com"
  />
  <association
    href="/workspaces/WKSP/associations/A2599698f8621a1468a892f6dbd903aea"
    from="/workspaces/WKSP/content/Samba3.xml?rev=1.0"
    kind="hasAuthor"
    to="/system/users/admin@calenco.com"
  />
  <association
    href="/workspaces/WKSP/associations/A375c043137a7bbc3d2fb69f3e75861fe"
    from="/workspaces/WKSP/publications/P1"
    kind="hasDepCalled"
    to="/workspaces/WKSP/content/Samba1.xml"
  />
  <association
    href="/workspaces/WKSP/associations/Aeb3eb77764d118410c2a086de921745e"
    from="/workspaces/WKSP/publications/P1"
    kind="hasDepCalled"
    to="DEFAULT"
  />
  <association
    href="/workspaces/WKSP/associations/A6c771935cf88a5f15acb7fdba431b49f"
    from="/workspaces/WKSP/content/Samba2.xml?rev=1.1"
    kind="hasAuthor"
    to="/system/users/admin@calenco.com"
  />
  <association
    href="/workspaces/WKSP/associations/Afea11258d2b4786e333b0d4f7592f680"
    from="/workspaces/WKSP/content/Samba1.xml?rev=1.0"
    kind="hasAuthor"
    to="/system/users/peter.pingus@calenco.com"
  />
  <association
    href="/workspaces/WKSP/associations/A253228d98f30d6b58c81be209fceec88"
    from="/workspaces/WKSP/content/Samba2.xml?rev=1.2"
    kind="hasAuthor"
    to="/system/users/peter.pingus@calenco.com"
  />
  <association
    href="/workspaces/WKSP/associations/A59917d67296fbc802cb31e39d793fa97"
    from="/workspaces/WKSP/content/Samba2.xml"
    kind="hasDepCalled"
    to="/workspaces/WKSP/content/sample_samba.gif"
  />
</associations>

JSON

{
  count:9,
  items: [
    {
      href:"/workspaces/WKSP/associations/A2182767000a0f12ac7d13c3bec015ee2",
      from:"/workspaces/WKSP/classifications/C1.1",
      kind:"isSubclassOf"
      to:"/workspaces/WKSP/classifications/C1",
    },
    {
      href:"/workspaces/WKSP/associations/A313e1a17a550665da2edd5e7b90f164c",
      from:"/workspaces/WKSP/content/Samba2.xml?rev=1.0",
      kind:"hasAuthor"
      to:"/system/users/peter.pingus@calenco.com",
    },
    {
      href:"/workspaces/WKSP/associations/A2599698f8621a1468a892f6dbd903aea",
      from:"/workspaces/WKSP/content/Samba3.xml?rev=1.0",
      kind:"hasAuthor"
      to:"/system/users/admin@calenco.com",
    },
    {
      href:"/workspaces/WKSP/associations/A375c043137a7bbc3d2fb69f3e75861fe",
      from:"/workspaces/WKSP/publications/P1",
      kind:"hasDepCalled"
      to:"/workspaces/WKSP/content/Samba1.xml",
    },
    {
      href:"/workspaces/WKSP/associations/Aeb3eb77764d118410c2a086de921745e",
      from:"/workspaces/WKSP/publications/P1",
      kind:"hasDepCalled"
      to:"DEFAULT",
    },
    {
      href:"/workspaces/WKSP/associations/A6c771935cf88a5f15acb7fdba431b49f",
      from:"/workspaces/WKSP/content/Samba2.xml?rev=1.1",
      kind:"hasAuthor"
      to:"/system/users/admin@calenco.com",
    },
    {
      href:"/workspaces/WKSP/associations/Afea11258d2b4786e333b0d4f7592f680",
      from:"/workspaces/WKSP/content/Samba1.xml?rev=1.0",
      kind:"hasAuthor"
      to:"/system/users/admin@calenco.com",
    },
    {
      href:"/workspaces/WKSP/associations/A253228d98f30d6b58c81be209fceec88",
      from:"/workspaces/WKSP/content/Samba2.xml?rev=1.2",
      kind:"hasAuthor"
      to:"/system/users/peter.pingus@calenco.com",
    },
    {
      href:"/workspaces/WKSP/associations/A59917d67296fbc802cb31e39d793fa97",
      from:"/workspaces/WKSP/content/Samba2.xml",
      kind:"hasDepCalled"
      to:"/workspaces/WKSP/content/sample_samba.gif",
    }
  ]
}

Retrieve Association ASSOC for Workspace WKSP

Roles

Request

GET /workspaces/WKSP/associations/ASSOC

Response

<?xml version="1.0" encoding="UTF-8"?>
<association
  href="/workspaces/WKSP/associations/A59917d67296fbc802cb31e39d793fa97"
  from="/workspaces/WKSP/content/Samba2.xml"
  kind="hasDepCalled"
  to="/workspaces/WKSP/content/sample_samba.gif"
/>

Notes

This API seems to be barely used, if at all. Deprecate?

Create Release for Workspace WKSP

Roles

Request

POST /workspaces/WKSP/releases

Field	Examples	Description
name	2010 Spring (2010.1), ProductName Version 1.6	A String with the name of the release

Responses

HTTP Response Code	Meaning
201	The named release is created for workspace WKSP with all files at their current revision. The current (creation) date and time is also stored
400	Required parameter "name" is missing, or empty
403	You don't have workspace administrator rights for workspace WKSP
409	A release with the given name already exists for workspace WKSP

List Releases for Workspace WKSP

Roles

Request

GET /workspaces/WKSP/releases

Response

<?xml version="1.0" encoding="UTF-8"?>
<releases count="3" wksp="WKSP">
  <release date="2010-07-17 17:29:45" href="/workspaces/WKSP/releases/My Release">My Release</release>
  <release date="2010-05-13 17:07:54" href="/workspaces/WKSP/releases/R2">R2</release>
  <release date="2010-02-10 11:26:39" href="/workspaces/WKSP/releases/R1">R1</release>
</releases>

Notes

This API seems to be barely used, if at all. Deprecate?

Remove Release REL from Workspace WKSP

Roles

Request

DELETE /workspaces/WKSP/releases/REL

Responses

HTTP Response Code	Meaning
204	Release REL was removed from workspace WKSP. Its files are not deleted, just the release grouping a given set of files
403	You don't have workspace administrator rights for workspace WKSP
404	Workspace WKSP doesn't have a release named REL

Notes

This API seems to be barely used, if at all. Deprecate?

Retrieve File FNAME from Release REL for Workspace WKSP

Roles

Request

GET /workspaces/WKSP/releases/REL/FNAME

See Files Naming

Responses

HTTP Response Code	Meaning
200	File FNAME from release REL for workspace WKSP is streamed to the client
400	File FNAME not found on release REL for workspace WKSP
403	You don't have rights to use workspace WKSP
404	Release REL not found on workspace WKSP

Notes

This API seems to be barely used, if at all. Deprecate? If we keep this API, HTTP 400 and HTTP 404 responses codes should be swapped, that is 404 should be returned if FNAME is not found, and 400 if REL is not found

List Stylesheets for Workspace WKSP

Roles

Request

GET /workspaces/WKSP/stylesheets

Response

{
  count:1,
  label:"name",
  identifier:"href",
  items: [
    {
      name:"[ DEFAULT ]",
      href:"DEFAULT"
    }
  ]
}

Notes

Only XSL stylesheets are returned, other stylesheet types, for example CSS, are not returned. To retrieve any stylesheet returned in the list, one has to then issue a normal 'get file' request

Retrieve File Dependencies Tree for Workspace WKSP

Roles

Request

GET /workspaces/WKSP/depstree?lang=LANG&classif=CLASSIF

Query Parameter	Description
lang	Optional. The langauge for which to get files for. `INTL` is used to mean common-to-all-languages (international) files
classif	Optional. The classification under which files to get deps tree for are. If it's not specified it means "All Files"

Response

{
  count:3,
  label:"name",
  items: [
    {
      author:"System Administrator",
      rev:"1.0",
      email:"admin@calenco.com",
      directory:true,
      name:"Samba1.xml",
      path:"/workspaces/WKSP/content/Samba1.xml",
      type:"DocBook5.0",
      size:1643
    },
    {
      author:"System Administrator",
      rev:"1.2",
      email:"peter.pingus@calenco.com",
      directory:true,
      name:"Samba2.xml",
      path:"/workspaces/WKSP/content/Samba2.xml",
      type:"DocBook5.0",
      size:6001,
      children: [
        {
          missing:true,
          name:"sample_samba.gif",
          path:"/workspaces/WKSP/content/sample_samba.gif",
          type:"unknown"
        }
      ]
    },
    {
      author:"System Administrator",
      rev:"1.0",
      email:"admin@calenco.com",
      directory:true,
      name:"Samba3.xml",
      path:"/workspaces/WKSP/content/Samba3.xml",
      type:"DocBook5.0",
      size:1995
    }
  ]
}

Retrieve File List for Workspace WKSP

Roles

Request

GET /workspaces/WKSP/filelist?lang=LANG&classif=CLASSIF

Query Parameter	Description
lang	Optional. The langauge for which to get files for. `INTL` is used to mean common-to-all-languages (international) files
classif	Optional. The classification under which files to get deps tree for are. If it's not specified it means "All Files"

Response

{
  count:3,
  label:"name",
  items:[
    {
      author:"System Administrator",
      rev:"1.0",
      lmod:"2010-07-16T17:41:05Z",
      email:"admin@calenco.com",
      name:"Samba1.xml",
      path:"/workspaces/WKSP/content/Samba1.xml",
      type:"DocBook5.0",
      size:1643
    },
    {
      author:"System Administrator",
      rev:"1.2",
      lmod:"2010-07-16T17:41:58Z",
      email:"peter.pingus@calenco.com",
      name:"Samba2.xml",
      path:"/workspaces/WKSP/content/Samba2.xml",
      type:"DocBook5.0",
      size:6001
    },
    {
      author:"System Administrator",
      rev:"1.0",
      lmod:"2010-07-16T17:41:19Z",
      email:"admin@calenco.com",
      name:"Samba3.xml",
      path:"/workspaces/WKSP/content/Samba3.xml",
      type:"DocBook5.0",
      size:1995
    }
  ]
}

List Available Toolchains

Roles

Request

GET /system/toolchains?cco_xmltype=XMLTYPE

Query Parameter

Description

Notes

cco_xmltype Any registered XML type (e.g. DocBook5.0) Optional. The XML type corresponding to a given add-on cco_xmltype is a property of an XML file

Responses

JSON

{
  count:10,
  label:"desc",
  identifier:"name",
  items: [
    {
      desc:"CHM Project",
      name:"DocBook5_to_CHM"
    },
    {
      desc:"HTML (multiple pages)",
      name:"DocBook5_to_HTML_Chunk"
    },
    {
      desc:"HTML (single page)",
      name:"DocBook5_to_HTML_Single"
    },
    {
      desc:"PDF",
      name:"DocBook5_to_PDF"
    },
    {
      desc:"PDF",
      name:"DITA_to_PDF"
    },
    {
      desc:"PS (PostScript)",
      name:"DocBook5_to_PS"
    },
    {
      desc:"RTF",
      name:"DocBook5_to_RTF"
    },
    {
      desc:"Screen Formats (html, chm, ...)",
      name:"DITA_to_HTML"
    },
    {
      desc:"XHTML (multiple pages)",
      name:"DocBook5_to_XHTML_Chunk"
    },
    {
      desc:"XHTML (single page)",
      name:"DocBook5_to_XHTML_Single"
    }
  ]
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<toolchains count="10">
  <toolchain name="DocBook5_to_CHM">CHM Project</toolchain>
  <toolchain name="DocBook5_to_HTML_Chunk">HTML (multiple pages)</toolchain>
  <toolchain name="DocBook5_to_HTML_Single">HTML (single page)</toolchain>
  <toolchain name="DocBook5_to_PDF">PDF</toolchain>
  <toolchain name="DITA_to_PDF">PDF</toolchain>
  <toolchain name="DocBook5_to_PS">PS (PostScript)</toolchain>
  <toolchain name="DocBook5_to_RTF">RTF</toolchain>
  <toolchain name="DITA_to_HTML">Screen Formats (html, chm, ...)</toolchain>
  <toolchain name="DocBook5_to_XHTML_Chunk">XHTML (multiple pages)</toolchain>
  <toolchain name="DocBook5_to_XHTML_Single">XHTML (single page)</toolchain>
</toolchains>

Retrieve Toolchain TCHAIN Details

Roles

Request

GET /system/toolchains/TCHAIN

Response

<?xml version="1.0" encoding="UTF-8">
<toolchain desc="PDF" name="TCHAIN">
  <param name="xincludes">
    Whether to resolve XInclude inclusions or not.
    If set to "true" inclusions will be resolved. Any other value will disable the feature.
    Default is "true".
  </param>
</toolchain>

Notes

This API seems to be barely used, if at all. Deprecate?

Retrieve File of Kind KIND for the AddOn ADDON

Roles

Request

GET /system/addons/ADDON/KIND

Possible values for KIND:

previewxsl : The XSLT file to be used for generating the HTML preview of an XML file associated with add-on ADDON

previewcss : The CSS file to be used with the HTML preview of an XML file generated with the preview XSL

schema : The (RNG) file containing the schema associated with XML file FNAME(???) of workspace WKSP

Responses

HTTP Response Code	Meaning
200	The file of kind KIND for the addon ADDON is streamed to the client
400	KIND is not one of the possible values
404	Addon ADDON doesn't exist, or it doesn't provide the file of kind KIND

List Available Languages

Roles

Request

GET /system/languages

Responses

JSON

{
  count:15,
  label:"name",
  identifier:"code",
  items:[
    {name:"Deutsch",code:"de"},
    {name:"Deutsch (Deutschland)",code:"de_DE"},
    {name:"English",code:"en"},
    {name:"English (United Kingdom)",code:"en_GB"},
    {name:"English (United States)",code:"en_US"},
    {name:"Español",code:"es"},
    {name:"Español (Argentina)",code:"es_AR"},
    {name:"Español (España)",code:"es_ES"},
    {name:"Français",code:"fr"},
    {name:"Français (Canada)",code:"fr_CA"},
    {name:"Français (France)",code:"fr_FR"},
    {name:"Italiano",code:"it"},
    {name:"Italiano (Italia)",code:"it_IT"},
    {name:"Português",code:"pt"},
    {name:"Português (Brasil)",code:"pt_BR"}
  ]
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<languages count="15">
  <language active="true" lang="de">Deutsch</language>
  <language active="true" lang="de_DE">Deutsch (Deutschland)</language>
  <language active="true" lang="en">English</language>
  <language active="true" lang="en_GB">English (United Kingdom)</language>
  <language active="true" lang="en_US">English (United States)</language>
  <language active="true" lang="es">Español</language>
  <language active="true" lang="es_AR">Español (Argentina)</language>
  <language active="true" lang="es_ES">Español (España)</language>
  <language active="true" lang="fr">Français</language>
  <language active="true" lang="fr_CA">Français (Canada)</language>
  <language active="true" lang="fr_FR">Français (France)</language>
  <language active="true" lang="it">Italiano</language>
  <language active="true" lang="it_IT">Italiano (Italia)</language>
  <language active="true" lang="pt">Português</language>
  <language active="true" lang="pt_BR">Português (Brasil)</language>
</languages>

Notes

The above is the list of supported languages as of version 2.1. If your language is not listed, please contact us and we'll be pleased to add it to the list of the supported languages.

Create Calenco User

Roles

Request

POST /system/users

Field	Description	Possible Values	Notes
email	The email address of the user	peter@pingusland.net, john@smit.com	This is the user's ID. It must match the user@domain pattern
pass	The password of the user	pingus123, VerySecret
name	Optional. The name of the user, if not specified "No Name" is set	Peter Pingus, John Smith, Lord Vader
wksp	Optional. The name of the primary workspace the user has access to	W1, My Workspace
role	Optional. The role this user has on the provided workspace, except for S. If not specified, R is set	R, A, S	R = Regular user; A = Workspace administrator; S = System Administrator
lang	Optional. The user's preferred language, if not specified "en" is set	en, en_US, es_AR, fr_FR	IETF code of the language. Note that this is not the potential UI language, but the language of the documents the user works the most with

Responses

HTTP Response Code	Meaning
201	The user was created and marked active (enabled)
400	Required parameters are missing, or empty
403	You don't have system administrator rights
409	A user with that email (ID) already exists

List Calenco Users

Roles

Request

GET /system/users

Responses

JSON

{
  count:3,
  items:[
    {
      email:"admin@calenco.com",
      name:"System Administrator",
      active:true,
      href:"/system/users/admin@calenco.com",
      lang:"en"
    },
    {
      email:"peter.pingus@calenco.com",
      name:"Peter Pingus",
      active:true,
      href:"/system/users/peter.pingus@calenco.com",
      lang:"en"
    },
    {
      email:"pub@calenco.com",
      name:"Special User Running Publications",
      active:true,
      href:"/system/users/pub@calenco.com",
      lang:"en"
    }
  ]
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<users count="3">
  <user active="true" email="admin@calenco.com" lang="en">System Administrator</user>
  <user active="true" email="peter.pingus@calenco.com" lang="en">Peter Pingus</user>
  <user active="true" email="pub@calenco.com" lang="en">Special User Running Publications</user>
</users>

Retrieve Details for Calenco User USER

Roles

Request

GET /system/users/USER

Response

<?xml version="1.0" encoding="UTF-8"?>
<user active="true" email="USER" lang="en">Peter Pingus</user>

Change Parameters for Calenco User USER

Roles

Request

PUT /system/users/USER

Field

Possible values

Description

Notes

name

Peter Pingus

The name of the user, if not specified "No Name" is set

pass

pingus

The user's password

lang

en_US

The user's new preferred language

IETF code of the language. Note that this is not the potential UI language, but the language of the documents the user works the most with

active

true, false

Whether the user is active

Only users with role S can set this, it is ignored for users without role S

Responses

HTTP Response Code	Meaning
200	The user parameters were changed
400	Required parameters are missing, or empty
403	You don't have system administrator rights, or are not USER

List Access Rights for Calenco User USER

Roles

Request

GET /system/usersrights/USER

Response

{
  count:1,
  sa:false,
  identifier:"wksp",
  items:[
    {role:"R",wksp:"/workspaces/WKSP"}
  ]
}

Grant Access Rights for Calenco User USER

Roles

Request

PUT /system/usersrights/USER

Field

Possible values

Description

Notes

wksp

The name of a workspace

The workspace for which the user's rights will be granted

role

R, A, S

The user's new role for the given workspace

If role is "S" the parameter "wksp" has no effect

Responses

HTTP Response Code	Meaning
200	Given access rights for USER are granted
400	Required parameters are missing, or empty
403	You don't have system administrator rights
404	The specified workspace cannot be found

Revoke Access Rights for Calenco User USER

Roles

Request

DELETE /system/usersrights/USER

HTTP Custom Request Header

Possible values

Description

Notes

X-Calenco-Workspace

The name of a workspace

The workspace for which the user's rights will be revoked

If this parameter is not specified, it is a request to revoke the system administrator right

Responses

HTTP Response Code	Meaning
204	All access rights for USER on the given workspace are revoked. USER will be unable to use the workspace until you grant his rights again
403	You don't have system administrator rights
404	The specified workspace cannot be found

Retrieve System Information

Roles

Request

GET /system/info

Response

{
  procs:2,
  os_name:"Linux",
  os_ver:"2.6.32-23-generic-pae",
  mem:118816768,
  os_arch:"i386",
  java_ver:"1.6.0_20",
  cco_ver:"2.1"
}

Files Naming

The parameter FNAME is composed as follows:

The language folder
A slash (/), if language folder is not empty
The file name

Examples:

Language folder	File	FNAME
fr_FR	legal-notice.xml	fr_FR/legal-notice.xml
	company-logo.png	company-logo.png

Download in other formats:

Plain Text

Context Navigation

Calenco V2.1 REST API

Table of Contents

Definitions

Notes

Possible HTTP Response Codes Summary

API Summary

Create Workspace

Roles

Request

Responses

List Workspaces

Roles

Request

Responses

JSON

XML

Notes

Change Workspace WKSP Status

Roles

Request

Responses

Backup Workspace WKSP

Roles

Request

Responses

Create Language for Workspace WKSP

Roles

Request

Responses

List Languages for Workspace WKSP

Roles

Request

Response

Change Status for Language LANG of Workspace WKSP

Roles

Request

Responses

Export Content for Workspace WKSP

Roles

Request

Responses

Store File in Language LANG for Workspace WKSP

Roles

Request

Responses

List Files in Language LANG for Workspace WKSP

Roles

Request

Responses

JSON

XML

Update File in Language LANG for Workspace WKSP

Roles

Request

Responses

Notes

Retrieve File FNAME of Workspace WKSP

Roles

Request

Responses

Export File FNAME of Workspace WKSP

Roles

Request

Responses

Notes

Remove File FNAME from Workspace WKSP

Roles

Request

Responses

Notes

Retrieve Metadata for File FNAME of Workspace WKSP

Roles

Request

Response

Notes

Allowed Methods for File FNAME of Workspace WKSP

Roles

Request

Response