Calenco REST API

Last modified: 2010/02/25 19:29 by fabian@neodoc.biz

This page defines a REST API for Calenco. It will superceed both the Actions URL proposal and Alternative Restful URL Schema specifications.

Table of Contents

  1. List workspaces
    1. Roles
    2. Request
    3. Response
    4. Notes
  2. Create workspace
    1. Roles
    2. Request
    3. Response
  3. Change workspace status
    1. Roles
    2. Request
    3. Response
  4. Backup workspace
    1. Roles
    2. Request
    3. Response
  5. Restore workspace
    1. Roles
    2. Request
    3. Form data
    4. Response
    5. Notes
  6. Create a language
    1. Roles
    2. Request
    3. Response
  7. Change language status
    1. Roles
    2. Request
    3. Response
  8. Export Content
    1. Roles
    2. Request
    3. Response
  9. List files
    1. Roles
    2. Request
    3. Response
  10. Store file
    1. Roles
    2. Request
    3. Response
  11. Retrieve file
    1. Roles
    2. Request
    3. Response
  12. Export file
    1. Roles
    2. Request
    3. Response
    4. Notes
  13. Delete file
    1. Roles
    2. Request
    3. Response
    4. Notes
  14. List properties of a file
    1. Roles
    2. Request
    3. Response
  15. Add/Change properties for a file
    1. Roles
    2. Request
    3. Response
  16. Remove property from a file
    1. Roles
    2. Request
    3. Response
  17. Get Revhistory Of A File
    1. Roles
    2. Request
    3. Response
  18. List Publications
    1. Roles
    2. Request
    3. Response
  19. Get Publication Details
    1. Roles
    2. Request
    3. Response
  20. Create Publication
    1. Roles
    2. Request
  21. Modify Publication
    1. Roles
    2. Request
  22. Delete Publication
    1. Roles
    2. Request
    3. Response
  23. Queue Publication
    1. Roles
    2. Request
    3. Response
  24. Get Publication Output
    1. Roles
    2. Request
    3. Response
  25. Create Comment
    1. Roles
    2. Request
    3. Response
  26. Get Comment
    1. Roles
    2. Request
    3. Response
  27. Create classification
    1. Roles
    2. Request
    3. Response
  28. List classifications
    1. Roles
    2. Request
    3. Response
  29. Get classification
    1. Roles
    2. Request
    3. Response
  30. Modify Classification
    1. Roles
    2. Request
    3. Response
  31. Classify File Set
    1. Roles
    2. Request
    3. Response
  32. Remove Classification
    1. Roles
    2. Request
    3. Response
  33. List Associations
    1. Roles
    2. Request
    3. Response
  34. Create Association
    1. Roles
    2. Request
  35. Get Association
    1. Roles
    2. Request
    3. Response
  36. Create Release
    1. Roles
    2. Request
    3. Response
  37. List Releases
    1. Roles
    2. Request
    3. Response
  38. List Release Files
    1. Roles
    2. Request
    3. Response
  39. Get File From Release
    1. Roles
    2. Request
    3. Response
  40. Delete Release
    1. Roles
    2. Request
    3. Response
  41. Get Workspace Stylesheets
    1. Roles
    2. Request
    3. Response
  42. Get Workspace Deps Tree
    1. Roles
    2. Request
    3. Response
  43. List Toolchains
    1. Roles
    2. Request
    3. Response
  44. Get Toolchain Details
    1. Roles
    2. Request
    3. Response
  45. Get AddOn File
    1. Roles
    2. Request
    3. Response
  46. List Available Languages
    1. Roles
    2. Request
    3. Response
  47. List Calenco users
    1. Roles
    2. Request
    3. Response
  48. Create Calenco user
    1. Roles
    2. Request
    3. Response
  49. Get details for a Calenco user
    1. Roles
    2. Request
    3. Response
  50. Modify Calenco user
    1. Roles
    2. Request
    3. Response
  51. Get Calenco User Rights
    1. Roles
    2. Request
    3. Response
  52. Grant User Rights
    1. Roles
    2. Request
    3. Response
  53. Revoke User Rights
    1. Roles
    2. Request
    3. Response
  54. Files Naming

Notes:

  • All URIs in requests are relative to a base Calenco URL, for example: https://calenco.com/
  • User roles are encoded as follows:
    • R : Regular (unprivileged) User
    • A : Account 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, which will be provided with HTTP basic authentication (over the encrypted SSL tunnel - HTTPS)
  • The payload of the Response in the 1st implementation attempts will be X(HT)ML, except for publications output (html, pdf), backups (zip), and binary content like images (png, jpeg, etc.). In the future, other representations (for example JSON) can be added
  • 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
  • For web browser clients, if not using an existing AJAX framework (dojo, YUI, etc.), PUT and DELETE requests will have to be crafted as described in  Using REST with AJAX. It could be considered to provide the method override in the query part of the request too: to be investigated
  • The API provides basic users management even if authentication is to be handled from the outside (OpenID, LDAP, simple HTTP authentication). When implementing authentication, consider the need (probably to handle ACLs) of the users management API, and remove it from this specification if it's not needed
  • Return values:
    • HTTP 200 (OK) if operation was successful
    • HTTP 201 (Created) if resource creation (POST) was successful
    • HTTP 202 (Accepted) if resource queuing (POST) was successful
    • HTTP 204 (No Content) if the resource was successfuly removed (DELETE)
    • HTTP 400 (Bad Request) if wrong/bad parameters were provided
    • HTTP 401 (Authorization Required) if credentials must be provided to access the requested resource
    • HTTP 403 (Forbidden) if the request cannot be performed, either because wrong credentials were supplied, or because the supplied credentials cannot be used to perform the desired request
    • HTTP 404 (Not Found) if a resource wasn't found at the requested URI
    • HTTP 409 (Conflict) if the operation can result in bad state, or conflicting resources
    • HTTP 500 (Internal Server Error) if the operation failed due to server processing (I/O, JCR, other exceptions)
    • If there are errors processing requests, a human-readable error message is returned in text/plain format
  • The "Impl?" column tracks prototype implementation status with the following code:
    • X : implemented
    • * : partly implemented
    • - : not implemented

API Summary

Impl? Request Media Type Detailed specs
X GET /workspaces text/xml List workspaces
X POST /workspaces application/x-www-form-urlencoded Create workspace
X PUT /workspaces/WKSP application/x-www-form-urlencoded Change workspace WKSP status
X GET /workspaces/WKSP application/zip Backup workspace WKSP
- PUT /workspaces/WKSP multipart/form-data Restore workspace WKSP
X POST /workspaces/WKSP/languages application/x-www-form-urlencoded Create language for workspace WKSP
X PUT /workspaces/WKSP/languages/LANG application/x-www-form-urlencoded Change status of langauge LANG for workspace WKSP
GET /workspaces/WKSP/content application/zip Export content for workspace WKSP
X GET /workspaces/WKSP/content/LANG text/xml List files in language LANG
X POST /workspaces/WKSP/content/LANG multipart/form-data Store file for workspace WKSP in language LANG
X GET /workspaces/WKSP/content/FNAME binary stream Retrieve file FNAME of workspace WKSP
X GET /workspaces/WKSP/content/FNAME application/zip Export file FNAME of workspace WKSP
* DELETE /workspaces/WKSP/content/FNAME Delete file FNAME of workspace WKSP
X GET /workspaces/WKSP/content/FNAME/properties text/xml List properties of file FNAME of workspace WKSP
X PUT /workspaces/WKSP/content/FNAME/properties/PNAME application/x-www-form-urlencoded Add/Change property PNAME of file FNAME of workspace WKSP
X DELETE /workspaces/WKSP/content/FNAME/properties/PNAME Delete property PNAME from file FNAME of workspace WKSP
X GET /workspaces/WKSP/content/FNAME/revhistory application/json Get Revision History details for file FNAME of workspace WKSP
X GET /workspaces/WKSP/publications text/xml List publications for workspace WKSP
X GET /workspaces/WKSP/publications/PUB text/xml Get details for publication PUB of workspace WKSP
X POST /workspaces/WKSP/publications application/x-www-form-urlencoded Create publication for workspace WKSP
X PUT /workspaces/WKSP/publications/PUB application/x-www-form-urlencoded Modify parameters for publication PUB of workspace WKSP
X DELETE /workspaces/WKSP/publications/PUB Delete publication PUB from workspace WKSP
X POST /workspaces/WKSP/pubsqueue application/x-www-form-urlencoded Queue publication for regeneration
X GET /workpsaces/WKSP/outputs/PUB binary stream Get output of publication PUB of workspace WKSP
- POST /worksapces/WKSP/comments application/x-www-form-urlencoded Create comment for workspace WKSP
- GET /workspaces/WKSP/comments/COMMENT text/xml Get comment COMMENT for workspace WKSP
X POST /workspaces/WKSP/classifications application/x-www-form-urlencoded Create classification for workspace WKSP
X GET /workspaces/WKSP/classifications text/xml List classifications for workspace WKSP
X GET /workspaces/WKSP/classifications/CLASSIFICATION text/xml Get classification CLASSIFICATION for workspace WKSP
X POST /workspaces/WKSP/classifications/CLASSIFICATION application/x-www-form-urlencoded Modify classification CLASSIFICATION for workspace WKSP
X PUT /workspaces/WKSP/classifications/CLASSIFICATION application/json Classify files under CLASSIFICATION for workspace WKSP
X DELETE /workspaces/WKSP/classifications/CLASSIFICATION application/json Remove classification CLASSIFICATION from workspace WKSP
X GET /workspaces/WKSP/associations text/xml List associations for workspace WKSP
X POST /workspaces/WKSP/associations application/x-www-form-urlencoded Create association for workspace WKSP
X GET /workspaces/WKSP/associations/ASSOC text/xml Get association ASSOC for workspace WKSP
X POST /workspaces/WKSP/releases application/x-www-form-urlencoded Create release for workspace WKSP
X GET /workspaces/WKSP/releases text/xml List releases for workspace WKSP
X GET /workspaces/WKSP/releases/REL text/xml List release REL files for workspace WKSP
X GET /workspaces/WKSP/releases/REL/FNAME binary stream Get file FNAME of release REL
X DELETE /workspaces/WKSP/releases/REL Delete release REL of workspace WKSP
X GET /workspaces/WKSP/stylesheets application/json Get XSL stylesheets for workspace WKSP
X GET /workspaces/WKSP/depstree application/json Get dependencies tree for workspace WKSP
X GET /system/toolchains text/xml List available toolchains
X GET /system/toolchains/TCHAIN text/xml Get toolchain TCHAIN details
X GET /system/addons/ADDON/KIND binary stream Get the file of kind KIND(previewcss, previewxsl, schema) associated with the add-on ADDON
X GET /system/languages application/x-www-form-urlencoded List available languages
X GET /system/users text/xml List Calenco users
X POST /system/users application/x-www-form-urlencoded Create Calenco user
X GET /system/users/USER text/xml Get details for Calenco user USER
X PUT /system/users/USER application/x-www-form-urlencoded Modify Calenco user USER
X GET /system/usersrights/USER json Get the rights for Calenco user USER
X PUT /system/usersrights/USER application/x-www-form-urlencoded Grant Rights for Calenco user USER
X DELETE /system/usersrights/USER application/x-www-form-urlencoded Revoke Rights for Calenco user USER
X GET /system/repository text/xml An XML view of the JCR repository data, only for users in group S

List workspaces

Roles

RA

Request

GET /workspaces

Response

<?xml version="1.0" encoding="UTF-8"?>
<workspaces count="4">
  <workspace active="true" href="/workspaces/w1" id="w1"
  uuid="bb2093ac-65de-4f87-857f-f7b9ff669573">NeoDoc
  SARL</workspace>
  <workspace active="true" href="/workspaces/w2" id="w2"
  uuid="e33ccd2c-7d92-4f99-8146-9eb4c2c758f1">Impika</workspace>
  <workspace active="true" href="/workspaces/w3" id="w3"
  uuid="bd3ab890-6c5f-497d-b00a-5f51e4fa44ad">Mandriva
  SA</workspace>
  <workspace active="true" href="/workspaces/w4" id="w4"
  uuid="3ac3267b-bf97-43c1-9a6c-c5e554dcb7c5">e-Cervo</workspace>
</workspaces>

Notes

If the user is S, all workspaces are listed. If the user is R or A, only workspaces he has access to are listed. If the user is non-existing, no workspaces are listed.

Create workspace

Roles

S

Request

POST /workspaces
Content-Type: application/x-www-form-urlencoded

Field Description Notes
description A descriptive name for the workspace, for example: NeoDoc, Impika, Mandriva S.A., Canonical, TIL Technologies, etc. There's no restriction on the allowed characters

Response

The workspace is created in the content repository and is marked active (enabled).

Change workspace status

Roles

S

Request

PUT /workspaces/WKSP
Content-Type: application/x-www-form-urlencoded

Field Possible Values Description Notes
active true, false Whether workspace WKSP is active or not

Response

Workspace WKSP changes status to enabled or disabled. Users cannot use disabled workspaces.

Backup workspace

Roles

A

Request

GET /workspaces/WKSP
Accept: application/zip

Response

The compressed (application/zip) backup file of workspace WKSP is streamed to the client.

Restore workspace

Roles

A

Request

PUT /workspaces/WKSP
Content-type: multipart/form-data

Form data

The application/zip file containing the backup to be restored for workspace WKSP.

Response

The workspace WKSP is restored to the state it was when backed up on the provided file.

Notes

The backup file provided is supposed to be one created by the Backup workspace API. Checks should be performed to be sure of this and an error should be returned if this is not the case.

Create a language

Roles

A

Request

POST /workspaces/WKSP/languages
Content-type: application/x-www-form-urlencoded

Field Possible values Description
lang Constrained from a list of available values provided by Calenco to fill the proper form element The code of the language to create

Response

The given language is associated with the given workspace, marked active, and the proper folders are created inside the workspace's content/ folder

Change language status

Roles

A

Request

PUT /workspaces/WKSP/languages/LANG
Content-type: application/x-www-form-urlencoded

Field Possible values Description Notes
active true, false Whether language LANG for workspace WKSP is active or not LANG cannot be empty, an error is returned if LANG is empty

Response

Language LANG for workspace WKSP changes status to enabled or disabled.

Export Content

Roles

RA

Request

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

Response

A compressed (application/zip) file of the content of workspace WKSP is streamed to the client.

List files

Roles

RA

Request

GET /workspaces/WKSP/content/LANG

Response

If LANG is empty (meaning 'list files common to all languages') then the response will look like this: 

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta content="text/html; charset=UTF-8" http-equiv="Conetnt-Type"/>
    <link href="/favicon.ico" rel="shortcut icon"/>
    <link href="/style.css" rel="stylesheet" type="text/css"/>
    <title>Calenco REST - International files for WKSP</title>
  </head>
  <body>
    <h1>Files in international language for workspace WKSP</h1>
    <ul class="dir">
      <li><span class="image-svg+xml"><a href="/workspaces/WKSP/content/drawing.svg">drawing.svg</a> rev=<span class="rev">1.0</span></span></li>
      <li><span class="image-png"><a href="/workspaces/WKSP/content/logo.png">logo.png</a> rev=<span class="rev">1.1</span></span></li>
      <li><span class="image-jpeg"><a href="/workspaces/WKSP/content/photo.jpg">photo.jpg</a> rev=<span class="rev">1.0</span></span></li>
      <li><span class="folder"><a href="/workspaces/w1/content/en">en</a></span></li>
      <li><span class="folder"><a href="/workspaces/w1/content/es_AR">es_AR</a></span></li>
    </ul>
    <form action="/workspaces/w1/content" enctype="multipart/form-data" method="POST">
      <label for="file">File to send: </label><input name="file" type="file"/>
      <input type="submit" value="Upload"/>
    </form>
    <p>Back to <a href="/workspaces">workspace list</a></p>
  </body>
</html>

If LANG is 'en' (meaning 'list files for the English language') then the response will look like this: 

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta content="text/html; charset=UTF-8" http-equiv="Conetnt-Type"/>
    <link href="/favicon.ico" rel="shortcut icon"/>
    <link href="/style.css" rel="stylesheet" type="text/css"/>
    <title>Calenco REST - en files for WKSP</title>
  </head>
  <body>
    <h1>Files in en language for workspace WKSP</h1>
    <ul class="dir">
      <li><span class="image-png"><a href="/workspaces/WKSP/content/en/user-prefs.png">user-prefs.png</a> rev=<span class="rev">1.0</span></span></li>
      <li><span class="text-plain"><a href="/workspaces/WKSP/content/en/options.txt">options.txt</a> rev=<span class="rev">1.0</span></span></li>
    </ul>
    <form action="/workspaces/WKSP/content/en" enctype="multipart/form-data" method="POST">
      <label for="file">File to send: </label><input name="file" type="file"/>
      <input type="submit" value="Upload"/>
    </form>
    <a href="/workspaces/WKSP">Back to workspace WKSP</a>
  </body>
</html>

Store file

Roles

RA

Request

POST /workspaces/WKSP/content/LANG
Content-type: multipart/form-data

If LANG is empty (or missing alltogether), the file is stored in the International (common to all languages) folder. The form provides the file to be stored.

Response

The provided file is stored in the content repository at the corresponding location according to LANG

Retrieve file

Roles

RA

Request

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

Field Possible Values Description Notes
rev 1, 2, 3, ... The revision of file FNAME of workspace WKSP to obtain Optional. If not specified, obtain the latest (HEAD) revision

See Files Naming

Response

The file is "streamed back" to the client.

Export file

Roles

RA

Request

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

See Files Naming

Response

A compressed archive (ZIP) containing FNAME for workspace WKSP and all its dependencies.

Notes

  • "all its dependencies" mean all dependencies stored in the content repository, external (URI) dependencies are not contained in the response
  • The latest (HEAD) revision of the file is exported

Delete file

Roles

RA

Request

DELETE /workspaces/WKSP/content/FNAME

Response

The file FNAME of workspace WKSP is deleted(, together with all its revisions?)

Notes

There is no dependencies checking of any kind, the file is just deleted from the content repository

List properties of a file

Roles

RA

Request

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

Field Possible Values Description Notes
pat "", "*", "cco_*", "myprop_*", ... A string describing the pattern to match property names Optional. If not specified, it's the same as specifying "*" (get all properties). Calenco-specific property names start with "cco_"

Response

If no pattern (or if the * pattern) specified: 

<?xml version="1.0" encoding="UTF-8"?>
<properties count="2" file="/FNAME" pattern="*">
  <property name="cco_size" type="long">3573</property>
  <property name="jcr:primaryType" type="name">nt:unstructured</property>
</properties>

If a pattern (for example, cco_*, to return all Calenco-specific properties) specified: 

<?xml version="1.0" encoding="UTF-8"?>
<properties count="1" file="/FNAME" pattern="cco_*">
  <property name="cco_size" type="long">3573</property>
</properties>

Add/Change properties for a file

Roles

RA

Request

PUT /workspaces/WKSP/content/FNAME/properties/PNAME
Content-type: application/x-www-form-urlencoded

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

Response

Property PNAME of file FNAME of workspace WKSP is added (if it wasn't there) or changed, Non-specified properties are left untouched

Remove property from a file

Roles

RA

Request

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

Response

Property PNAME of file FNAME of workspace WKSP is deleted

Get Revhistory Of A File

Roles

RA

Request

GET /workspaces/WKSP/content/FNAME/revhistory

Response

{
"count":2,
"revisions":[
    {"author":"Root of All Evil","rev":"1.1","name":"FNAME","date":"20100108","href":"/workspaces/WKSP/content/FNAME?rev=1.1"},
    {"author":"Some other Author","rev":"1.0","name":"FNAME","date":"20100107","href":"/workspaces/WKSP/content/FNAME?rev=1.0"}
  ]
}

List Publications

Roles

RA

Request

GET /workspaces/WKSP/publications

Response

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <title>Calenco REST - Publications for workspace WKSP</title>
  </head>
  <body>
    <h1>Publications for workspace <a class="workspace" href="/workspaces/WKSP">WKSP</a></h1>
    <ul class="publications">
      <li class="pub" id="p1"><a href="/workspaces/WKSP/publications/p1">Java User Guide in PDF</a></li>
      <li class="pub" id="p2"><a href="/workspaces/WKSP/publications/p2">Java User Guide in PDF (A5)</a></li>      
    </ul>
  </body>
</html>

Get Publication Details

Roles

RA

Request

GET /workspaces/WKSP/publications/PUB

Response

<?xml version="1.0" encoding="UTF-8"?>
<publication type="manual" id="p342" status="success" updated="2009-04-19" name="Java User Guide in PDF">
  <input input-type="DocBook5.0" href="/workspaces/WKSP/content/en/Master-Java-UG.xml" input-release="Version 1.2" />
  <toolchain name="PDF">
    <param name="images.dpi" value="300" />
    <param name="do.xinclude" value="yes" />
  </toolchain>
  <xsl href="/workspaces/NeoDoc/content/fo-hires.xsl" xsl-release="Version 1.4">
    <param name="paper.type" value="A4" />
  </xsl>
  <output zip="true" href="/workspaces/WKSP/outputs/PUB/Java-UG.pdf" />
</publication>

Possible values for the status attribute are

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

Create Publication

Roles

A

Request

POST /workspaces/WKSP/publications
Content-type: application/x-www-form-urlencoded

Field Possible values Description Notes
name String The name of the publication
input URI, example : /workspaces/WKSP/content/en/Master-Starter.xml The file to publish See Files Naming
input-type String The type of XML file as DocBook, DITA, Globekid, ... See http://trac.calenco.com/wiki/CalencoCompilationSpecs
input-release String, the name of the input release The release the file to publish belongs to Optional. If ommited, publish the latest revision (HEAD) of the file and its dependencies. If specified, the file and its dependencies are taken from the specified release
toolchain String (PDF, HTML, XHTML, ...) The toolchain to use
tparams images.dpi=300;do.xincludes=yes Multiple-value list of the toolchain params Optional
xsl URI The XSL to use See Files Naming
xsl-release String, the name of the xsl release The release the xsl file belongs to Optional. If ommited, take the latest revision (HEAD) of the xsl and its dependencies. If specified, the xsl and its dependencies are taken from the specified release
xslparams paper.type=A4 Multiple-value list of the XSL params Optional
output Java-UG-HIRES File name of compiled output, minus the extension If output is not self-contained (for example HTML), this will be the name of the folder containing output files
zip true, false If the output is to be zipped
type manual, automatic, immediate "manual" : publication is triggered by hand. "automatic" : this publication should be automatically updated (republished) when one of its dependencies change. "immediate" : launch compilation directly, do not put it in the queue.
method file, dav How I want this to be published, as a file, or through WebDAV If method is absent, 'file' is assumed
dav-user DavServerUserName User name to authenticate on the DAV server If this is specified, and method is missing, method is assumed to be 'dav', and dav-pass must be specified also
dav-pass DavServerPassword Password to authenticate on the DAV server If dav-user is specified, and dav-pass is ommited, an error is returned
dav-port 8765 The port the DAV server is listening onto Optional. If not specified, use the standard WebDAV port: 80

Modify Publication

Roles

A

Request

PUT /workspaces/WKSP/publications/PUB
Content-type: application/x-www-form-urlencoded

Field Possible values Description Notes
tparams images.dpi=300;do.xincludes=yes Multiple-value list of the toolchain params Optional
xslparams paper.type=A4 Multiple-value list of the XSL params Optional
output Java-UG-HIRES File name of compiled output, minus the extension If output is not self-contained (for example HTML), this will be the name of the folder containing output files
type manual, automatic, immediate "manual" : publication is triggered by hand. "automatic" : this publication should be automatically updated (republished) when one of its dependencies change. "immediate" : launch compilation directly, do not put it in the queue.
method file, dav How I want this to be published, as a file, or through WebDAV If method is absent, 'file' is assumed
dav-user DavServerUserName User name to authenticate on the DAV server If this is specified, and method is missing, method is assumed to be 'dav', and dav-pass must be specified also
dav-pass DavServerPassword Password to authenticate on the DAV server If dav-user is specified, and dav-pass is ommited, an error is returned
dav-port 8765 The port the DAV server is listening onto Optional. If not specified, use the standard WebDAV port: 80

Delete Publication

Roles

A

Request

DELETE /workspaces/WKSP/publications/PUB

Response

Publication PUB is deleted from workspace WKSP. TODO: What happens with outputs of publication PUB? Are they also deleted? (I think they should be) Are they left available?

Queue Publication

Roles

A

Request

POST /workspaces/WKSP/pubsqueue
Content-type: application/x-www-form-urlencoded

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

Response

If a publication with the given name exists in workspace WKSP, it's (re)queued for publication and an HTTP 202 (Accepted) status is set. Otherwise an error message is returned with an HTTP 404 (Not Found) error status

Get Publication Output

Roles

RA

Request

GET /workspaces/WKSP/outputs/PUB

Response

If output is self-contained (for example, a PDF file), then its contents are streamed back to the client; otherwise a compressed (application/zip) file with all files of output content for publication PUB of workspace WKSP is streamed back to the client.

Create Comment

Roles

RA

Request

POST /workspaces/WKSP/comments
Content-type: application/x-www-form-urlencoded

Field Possible values Description Notes
comment This is a comment The comment itself
xpointer /workspaces/WKSP/content/fr/intro.xml#p1 The XPointer to the element inside the file to apply the comment onto p1 is the ID of the element of the fr/intro.xml file to apply the comment onto

Response

Comment is created and associated with the given element of the given XML file. An association with predicate hasComment is also created.

Get Comment

Roles

RA

Request

GET /workspaces/WKSP/comments/COMMENT

Response

<?xml version="1.0" encoding="UTF-8"?>
<comment id="COMMENT" xpointer="/workspaces/WKSP/content/fr/intro.xml#p1">This is a comment</comment>

Create classification

Roles

RA

Request

POST /workspaces/WKSP/classifications
Content-type: application/x-www-form-urlencoded

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

Response

The named classification is created, and available to be used with associations to create ontologies.

List classifications

Roles

RA

Request

GET /workspaces/WKSP/classifications

Note: One can also specify the desired format of the response by appending it to the request, for example GET /workspaces/WKSP/classifications.json to get the response in JSON. Supported formats are XML, JSON and HTML

Response

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <title>Calenco REST - Classifications for workspace WKSP</title>
  </head>
  <body>
    <h1>Classifications for workspace <a class="workspace" href="/workspaces/WKSP">WKSP</a></h1>
    <ul class="classifications">
      <li class="classification"><a href="/workspaces/WKSP/classifications/My%20Project">My Project</a></li>
      <li class="classification"><a href="/workspaces/WKSP/classifications/By%20geolocation">By geolocation</a></li>      
    </ul>
  </body>
</html>

Get classification

Roles

RA

Request

GET /workspaces/WKSP/classifications/CLASSIFICATION

Response

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

Modify Classification

Roles

RA

Request

POST /workspaces/WKSP/classifications/CLASSIFICATION
Content-type: application/x-www-form-urlencoded

Field Description Examples
name The new name of the classification "My Classification"

Response

Classification CLASSIFICATION is renamed to the given name and all associations referring to it are updated

Classify File Set

Roles

RA

Request

PUT /workspaces/WKSP/classifications/CLASSIFICATION
Content-type: application/x-www-form-urlencoded

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"]

Response

The action taken depends on the classification name:

  • Attic. Files are moved to the Attic classification and removed from all other classifications. Files in the Attic do not appear in file trees, and can only be Recovered to make them available again
  • Other classification names. Files are classified under CLASSIFICATION and removed from the Attic, if needed.

Remove Classification

Roles

RA

Request

DELETE /workspaces/WKSP/classifications/CLASSIFICATION

If you want to remove files from a classification (as oposed to removing the classification itself), you must provide the custom HTTP header X-Calenco-Filelist whose value must be a JSON array of the URIs of files to remove from CLASSIFICATION, for example:
X-Calenco-Filelist: ["/workspaces/WKSP/content/logo.png", "/workspaces/WKSP/content/en_US/intro.xml"]

Response

Custom HTTP header present CLASSIFICATION Action
Yes "Attic" Files are recovered from the Attic and available under the "All Files" classification to be used again
Yes Not "Attic" Files are removed from CLASSIFICATION
No "Attic" or "ALL_FILES" Bad request, HTTP 400 is returned
No Nor "Attic", neither "ALL_FILES" CLASSIFICATION is deleted, and also all associations referring to it

List Associations

Roles

RA

Request

GET /workspaces/WKSP/associations?from=FROM_FILE&kind=ASSOC_KIND&to=RESOURCE

Optional query parameters are:

Parameter Description
from Match only the given origin file
kind Match only the given association type
to Match only the given target resource

For example, the following request

GET /workspaces/WKSP/associations?kind=hasDepCalled&to=en/intro.xml

would return all files that have en/intro.xml as a dependency, while the following request

GET /workspaces/WKSP/associations?kind=isClassifiedOnto&to=/workspaces/WKSP/classifications/MyProject

would return all files belonging to MyProject (one of the possible classifications)

Response

<?xml version="1.0" encoding="UTF-8"?>
<associations count="14">
  <association from="/workspaces/WKSP/content/en/SambaLDAPArticle.xml" kind="hasDepCalled" to="/workspaces/WKSP/content/en/Samba3.xml"/>
  <association from="/workspaces/WKSP/content/en/SambaLDAPArticle.xml" kind="hasDepCalled" to="/workspaces/WKSP/content/en/Samba4.xml"/>
  <association from="/workspaces/WKSP/content/en/SambaLDAPArticle.xml" kind="hasDepCalled" to="/workspaces/WKSP/content/en/Samba5.xml"/>
  <association from="/workspaces/WKSP/content/en/SambaLDAPArticle.xml" kind="hasDepCalled" to="/workspaces/WKSP/content/en/Samba1.xml"/>
  <association from="/workspaces/WKSP/content/en/SambaLDAPArticle.xml" kind="hasDepCalled" to="/workspaces/WKSP/content/en/Samba6.xml"/>
  <association from="/workspaces/WKSP/content/en/Samba2.xml" kind="hasDepCalled" to="/workspaces/WKSP/content/en/sample_samba.gif"/>
  <association from="/workspaces/WKSP/content/en/SambaLDAPArticle.xml" kind="hasDepCalled" to="/workspaces/WKSP/content/en/Samba2.xml"/>
</associations>

Create Association

Roles

RA

Request

POST /workspaces/WKSP/associations
Content-type: application/x-www-form-urlencoded

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

Get Association

Roles

RA

Request

GET /workspaces/WKSP/associations/ASSOC

Response

<?xml version="1.0" encoding="UTF-8"?>
<association
    href="/workspaces/WKSP/associations/6570f4506451789ea829a9dabe10d133"
    from="/workspaces/WKSP/content/SambaLDAPArticle.xml"
    kind="hasDepCalled"
    to="/workspaces/WKSP/content/Samba1.xml" />

Create Release

Roles

A

Request

POST /workspaces/WKSP/releases
Content-type: application/x-www-form-urlencoded

Field Possible values Description Notes
name 2009 Summer A String with the name of the release

Response

A new release is created for workspace WKSP with all files, at their current revision, corresponding to this release. The current (creation) date and time is also stored.

List Releases

Roles

RA

Request

GET /workspaces/WKSP/releases

Response

<?xml version="1.0" encoding="UTF-8"?>
<releases count="3" wksp="WKSP_NAME">
  <release date="2009-04-10 00:00:23" href="/workspaces/WKSP/releases/2009 Spring">2009 Spring</release>
  <release date="2008-10-14 11:23:53" href="/workspaces/WKSP/releases/2009">2009</release>
  <release date="2008-03-30 12:03:40" href="/workspaces/WKSP/releases/2008.1 (Spring)">2008.1 (Spring)</release>
</releases>

List Release Files

Roles

RA

Request

GET /workspaces/WKSP/releases/REL

Response

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<dir count="5">
  <entry class="file" href="/workspaces/WKSP/releases/REL/pci.txt" ver="1.2">pci.txt</entry>
  <entry class="file" href="/workspaces/WKSP/releases/REL/repository.xml" ver="1.0">repository.xml</entry>
  <entry class="file" href="/workspaces/WKSP/releases/REL/Windows7RC-Key.pdf" ver="1.0">Windows7RC-Key.pdf</entry>
  <entry class="file" href="/workspaces/WKSP/releases/REL/266182_Camp Darby.jpg" ver="1.0">266182_Camp Darby.jpg</entry>
  <entry class="folder" href="/workspaces/WKSP/releases/REL/en">en</entry>
</dir>

Get File From Release

Roles

RA

Request

GET /workspaces/WKSP/releases/REL/FNAME

See Files Naming

Response

The file FNAME belonging to release REL (that is, at the revision specified in the release) is streamed back to the client.

Delete Release

Roles

A

Request

DELETE /workspaces/WKSP/releases/REL

Response

Release REL of workspace WKSP is deleted. Its files are not deleted, just the release grouping a given set of files.

Get Workspace Stylesheets

Roles

RA

Request

GET /workspaces/WKSP/stylesheets
Accept: application/json

Response

{"count":1,"stylesheets":[{"name":"simple_db5_xhtml.xsl","href":"/workspaces/WKSP/content/simple_db5_xhtml.xsl"}]}

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

Get Workspace Deps Tree

Roles

RA

Request

GET /workspaces/WKSP/depstree?lang=LANG&classif=CLASSIF
Accept: application/json

Optional query parameters are:

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

Response

{
"items":[
	{"rev":"1.0","directory":true,"name":"SambaLDAPArticle.xml","path":"/workspaces/WKSP/content/SambaLDAPArticle.xml",
	"children":[
		{"rev":"1.0","name":"Samba5.xml","path":"/workspaces/WKSP/content/Samba5.xml","type":"text/xml","size":4041},
		{"rev":"1.0","name":"Samba2.xml","path":"/workspaces/WKSP/content/Samba2.xml",
		"children":[
			{"rev":"1.0","name":"sample_samba.gif","path":"/workspaces/WKSP/content/sample_samba.gif","type":"image/gif","size":54997}
		],
		"type":"text/xml","size":6001},
		{"rev":"1.0","name":"Samba1.xml","path":"/workspaces/WKSP/content/Samba1.xml","type":"text/xml","size":1643},
		{"rev":"1.0","name":"Samba4.xml","path":"/workspaces/WKSP/content/Samba4.xml","type":"text/xml","size":6690},
		{"rev":"1.0","name":"Samba3.xml","path":"/workspaces/WKSP/content/Samba3.xml","type":"text/xml","size":1995},
		{"rev":"1.0","name":"Samba6.xml","path":"/workspaces/WKSP/content/Samba6.xml","type":"text/xml","size":1353}
	],
	"type":"text/xml","size":3764}
	],
"label":"name"
}

List Toolchains

Roles

RA

Request

GET /system/toolchains?cco_xmltype=DocBook5.0

Note: One can also specify the desired format of the response by appending it to the request, for example GET /workspaces/WKSP/toolchains.json?cco_xmltype=DocBook5.0 to get the response in JSON. Supported formats are XML, JSON and HTML

Field Possible values Description Notes
cco_xmltype any registered XML type (e.g. DocBook5.0) Optional. The XML type corresponding to a given add-on The cco_xmltype is a property of a file

Response

<?xml version="1.0" encoding="UTF-8"?>
<toolchains>
  <toolchain name="docbook2pdf-hires">Convert DocBook to PDF (High Resolution)</toolchain>
  <toolchain name="docbook2dita">Convert DocBook to DITA</toolchain>
  <toolchain name="dita2html">Convert DITA to HTML</toolchain>
</toolchains>

Get Toolchain Details

Roles

RA

Request

GET /system/toolchains/TCHAIN

Response

<?xml version="1.0" encoding="UTF-8"?>
<toolchain name="docbook2pdf-hires" desc="Convert DocBook to PDF (High Resolution)">
  <param name="do.xincludes" type="boolean" />
  <param name="images.dpi" type="integer" />
  <!-- Other parameter definitions listed here -->
</toolchain>

Get AddOn File

Roles

RA

Request

GET /system/addons/ADDON/KIND

Response

The file of type KIND associated with the add-on ADDON.

KIND can be:

  • 'previewxsl' : The XSLT1.0 file to be used for generating 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.

Processing expectations:

  • if the add-on does not exist or if it does not provide those resources, an "HTTP 404 Not Found" is returned.

List Available Languages

Roles

RA

Request

GET /system/languages

Note: One can also specify the desired format of the response by appending it to the request, for example GET /system/languages.json to get the response in JSON. Supported formats are JSON and XML

Response

<?xml version="1.0" encoding="UTF-8">
<languages count="15">
  <language active="true" lang="en">English</language>
  <language active="true" lang="en_US">English (United States)</language>
  <language active="true" lang="en_GB">English (United Kingdom)</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_FR">Français (France)</language>
  <language active="true" lang="fr_CA">Français (Canada)</language>
  <language active="true" lang="de">Deutsch</language>
  <language active="true" lang="de_DE">Deutsch (Deutschland)</language>
  <language active="true" lang="pt">Português</language>
  <language active="true" lang="pt_BR">Português (Brasil)</language>
  <language active="true" lang="it">Italiano</language>
  <language active="true" lang="it_IT">Italiano (Italia)</language>
</languages>

List Calenco users

Roles

S

Request

GET /system/users

Response

<?xml version="1.0" encoding="UTF-8"?>
<users count="2">
  <user active="true" email="admin@calenco.com" lang="en">Root of
  All Evil</user>
  <user active="true" email="fabian@neodoc.biz" lang="en">Fabian
  Mandelbaum</user>
</users>

Another possibility (Users management is still under development) would be:

<users>
  <user email="peter@pingusland.net" name="Peter Pingus" active="false">
   <workspaces>
      <workspace name="PingusLand" role="R" />
    </workspaces>
    <lang code="en_US" />
  </user>
  <user email="admin@calenco.com" name="Calenco System Administrator" active="true">
    <workspaces>
      <workspace name="admin" role="S" />
    </workspaces>
    <lang code="fr_FR" />
  </user>
  <user email="wkspamdin@pingusland.net" name="Workspace Admin for Pingusland" active="true">
    <workspaces>
      <workspace name="PingusLand" role="A" />
      <workspace name="Another Workspace" role="R" />
    </workspaces>
    <lang code="en_US" />
  </user>
</users>

Create Calenco user

Roles

S

Request

POST /system/users
Content-type: application/x-www-form-urlencoded

Field Possible values Description Notes
email peter@pingusland.net Mandatory. The email address of the user This is the user's ID. If it doesn't conform to the user@domain pattern, an error is returned
pass pingus Mandatory. The user's password
wksp w1 Mandatory. The id of the primary workspace this user is allowed to use
name Peter Pingus Optional. The name of the user, if not specified "No Name" is set
role R, A, S Optional. The role this user has on the provided workspace, except for S. If not specified, R is set R = Regular user; A = Workspace administrator; S = System Administrator
lang en_US Optional. The user's preferred language, if not specified "en" is set IETF code of the language

Response

A Calenco user is created.

Get details for a Calenco user

Roles

RAS

Request

GET /system/users/USER

Response

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

Modify Calenco user

Roles

RAS

Request

PUT /system/users/USER
Content-type: application/x-www-form-urlencoded

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
active true, false Whether the user is active Only users with role S can set this, it is ignored for users without role S

Response

User USER data is modified.

Get Calenco User Rights

Roles

S

Request

GET /system/usersrights/USER

Response

{ sysadmin: false, rights: [ {wksp: "w1", role:"A"}, {wksp: "w2", role: "R"} ] }
{ sysadmin: true, rights: [] } (System administrators have access to anything)

Grant User Rights

Roles

S

Request

PUT /system/usersrights/USER
Content-type: application/x-www-form-urlencoded

Field Possible values Description Notes
wksp the name of a workspace The workspace for which the user's rights will be granted If the new role of the user is "S" this parameter has no effect and shall be omitted
role one of "R", "A", "S" The user's new role for the given workspace If role is "S" the parameter "wksp" has no effect

Response

The rights of USER, for the given workspace (if role is "A" or "R"), are modified.

Revoke User Rights

Roles

S

Request

DELETE /system/usersrights/USER

Revoke a right for user USER.

The workspace for which all user USER rights will be revoked has to be specified in custom HTTP header 'X-Calenco-Workspace'. If this parameter is not specified, it is a request to revoke the system administrator right to user USER.

Field 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.

Response

The rights of the user USER, for the given workspace, if provided, are revoked. If a workspace parameter is not provided the system administrator right for user USER(if existing) is revoked.

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