Back to JeCARS homepage

JeCARS Documentation

(NI) = Not yet implemented
(TBS) = To be specified

REST API JeCARS

Introduction
General

Outputs

Atom
HTML
Simple

Authentication

Using BASIC authentication
Using GData authentication

Operations

GET (Retrieving information)

Parameters

POST (Creating information)

Creation of nodes
Creating an object using copy
Creation using the slug HTTP header
Parameters as URL parameters
Error codes

PUT (Update information)

Node updating
Updating multivalue properties

DELETE (Delete information)

Deletion of nodes
Parameters
Error codes

HTTP Status codes

Output formats

atom

JeCARS

Node types
Property types
Special Property types

_crypt

Permissions and access rights
User and Group management
Versioning

Introduction

Outputs

Atom

HTML

Simple

General

Authentication

Using BASIC authentication

To use basic HTTP authentication, just send the username and password combination you normally use to log in along with the request.

HTTP

GET /..../JeCARS/default/Users HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Using GData authentication

JeCARS's GData authentication is following the rules set in; http://code.google.com/apis/accounts/AuthForInstalledApps.html

To authenticate the user, send a POST request to the following URL (when using the JeCARS default installation:

http://localhost:8080/cars/accounts/ClientLogin

ClientLogin can be used with any application that can make an HTTPS POST request. The POST request should be structured as a form post with the default encoding:
application/x-www-form-urlencoded. Parameters should be included in the body of the post.

It is also possible to use the HTTP GET request by applying the X-HTTP-Method-Override parameter.

JeCARS supports the following parameters;

Parameter	Meaning	Notes
Email	User id	e.g. Email=Administrator In JeCARS the value is most of the time the username (not the email address).
Passwd	User password

If the request succeeds, then the response contains an alphanumeric string labeled Auth.

After a successful authentication request, use the Auth value to create an Authorization header for each request:

Authorization: GoogleLogin auth=yourAuthValue

It is also possible to supply the Auth value as URL parameter. Use GOOGLELOGIN_AUTH=yourAuthValue parameter.

Operations

GET

To get a list of nodes a HTTP GET request is being send.

HTTP

GET {server:port}cars/JeCARS/default/Users

The first example is to retrieve the available users of the JeCARS repository.
In a default installation enter;

http://localhost:8080/cars/JeCARS/default/Users

The result is;

HTTP

200 OK

<?xml version="1.0" encoding='utf-8'?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
 xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:jecars="http://jecars.org">
<title>Users</title>
<author><name>jecars.org</name></author>
<rights>(C) 2007</rights>
<link rel="self" type="application/atom+xml" href="http://localhost:8080/cars/JeCARS/default/Users"/>
<link rel="alternate" type="application/atom+xml" href="http://localhost:8080/cars/JeCARS/default/Users"/>
<link rel="edit" type="application/atom+xml" href="http://localhost:8080/cars/JeCARS/default/Users"/>
<published>2007-09-17T14:57:30.967+02:00</published>
<updated>2007-09-17T14:57:30.967+02:00</updated>

<id>%2FJeCARS%2Fdefault%2FUsers</id>
<category term='jecars:Users'/>
<jcr:created>2007-09-17T14:57:30.967+02:00</jcr:created>
<jcr:primaryType>jecars%3AUsers</jcr:primaryType>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:jecars="http://jecars.org/">
<title>Superuser</title>
<author><name>jecars.org</name></author>
<rights>(C) 2007</rights>
<link rel="alternate" type="application/atom+xml" href="http://localhost:8080/cars/JeCARS/default/Users/Superuser"/>

<link rel="edit" type="application/atom+xml" href="http://localhost:8080/cars/JeCARS/default/Users/Superuser"/>
<published>2007-09-17T14:57:30.967+02:00</published>
<updated>2007-09-17T14:57:30.967+02:00</updated>
<id>urn:uuid:2bc70b99-3037-4e08-8d31-a7fdb95dc85d</id>
<category term='jecars:User'/>
</entry>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:jecars="http://jecars.org/">
<title>Administrator</title>
<author><name>jecars.org</name></author>
<rights>(C) 2007</rights>

<link rel="alternate" type="application/atom+xml" href="http://localhost:8080/cars/JeCARS/default/Users/Administrator"/>
<link rel="edit" type="application/atom+xml" href="http://localhost:8080/cars/JeCARS/default/Users/Administrator"/>
<published>2007-09-17T14:57:30.975+02:00</published>
<updated>2007-09-17T15:16:40.729+02:00</updated>
<id>urn:uuid:c02d1448-dce8-4363-9b9e-6c4703f598c7</id>
<category term='jecars:User'/>
</entry>
</feed>

The URL can have any number of parameters they are entered in form ?...=...&...=...

Parameters

The standard query parameters are summarized in the following table. All parameter values need to be URL encoded.

Parameter	Meaning	Notes
q	Full-text query string	See example
-/category	Category filter	The term category is in JeCARS being mapped on to a JCR NodeType The category will also being mapped to the jecars: namespace. List all categories before any other query parameters.
alt	Alternative representation type	If you don't specify an alt parameter, the service returns an Atom feed. This is equivalent to alt=atom. alt=html returns an html result. alt=atom_entry returns only the <entry> part of the object alt=simple returns an simple text result. alt=edit_html returns a simple html editable form to perform some simple manipulation. (NI) alt=atomsvc return a service document which is used by Atom APP client to discover capabilities and locations of the available Collections
updated-min, updated-max	Bounds on the entry update date	Use the ISO 8601:2000 timestamp format. For example: 2005-08-09T10:57:00.000-08:00 Or use now[-/+][value][s\|m\|h\|d]. e.g. now-2h to get a timestamp of the current time minus 2 hours use now+3h to get a timestamp 3 hours ahead of the current time now-2m to get a timestamp of the current time minus 2 minutes s = seconds m = minutes h = hours d = days The lower bound is inclusive, whereas the upper bound is exclusive.
published-min, published-max	Bounds on the entry publication date	Use the ISO 8601:2000 timestamp format. For example: 2005-08-09T10:57:00.000-08:00 Or use the now[-/+] parameter. now-2h to get a timestamp of the current time minus 2 hours use now+3h to get a timestamp 3 hours ahead of the current time now-2m to get a timestamp of the current time minus 2 minutes s = seconds m = minutes h = hours d = days The lower bound is inclusive, whereas the upper bound is exclusive.
start-index	1-based index of the first result to be retrieved	Note that this isn't a general cursoring mechanism. If you first send a query with ?start-index=1&max-results=10 and then send another query with ?start-index=11&max-results=10, the service cannot guarantee that the results are equivalent to ?start-index=1&max-results=20, because insertions and deletions could have taken place in between the two queries.
max-results	Maximum number of results to be retrieved	For any service that has a default max-results value (to limit default feed size), you can specify a very large number if you want to receive the entire feed.
xpath	Xpath search	The given xpath query will be used to generate the results. The query will only result in the current available objects in JeCARS. If e.g. there are dynamic application sources in JeCARS those objects won’t be updated before executing the query. The sql option cannot be combined with other options.
sql	SQL search	The given sql query will be used to generate the results. The query will only result in the current available objects in JeCARS. If e.g. there are dynamic application sources in JeCARS those objects won’t be updated before executing the query. The sql option cannot be combined with other options.
references	Retrieve the references of this object	Returns the list of references to this object. Only the objects are returned with read permission. references=property
rights	Retrieve the access rights of this object	rights={object path}
childnodedefs	Retrieve the allowed child node types of this object	Returns the list of allowed child node type of this object. childnodedefs=property
deep	Include the children in the search.	If =true then the children object are also included in the search. the default is false.
created-min, created-max	Bounds on the entry create date	Use the ISO 8601:2000 timestamp format. For example: 2005-08-09T10:57:00.000-08:00 Or use the now[-/+] parameter. now-2h to get a timestamp of the current time minus 2 hours use now+3h to get a timestamp 3 hours ahead of the current time now-2m to get a timestamp of the current time minus 2 minutes s = seconds m = minutes h = hours d = days The lower bound is inclusive, whereas the upper bound is exclusive.
keywords	Search on keywords.	(TBS)
this-node	How to render “this node”	If =not then the current node will not being rendered in the output. Mostly used when output search results.
version-history	Show the version history of this object	(TBS)
orderby	Order the results	The field which is used to order the results
orderbytype	Ordering specifier	The ordering of the results DESC ASC

q

HTTP

http://localhost:8080/cars/JeCARS/default/Users?q=Administrator

This syntax is based on the syntax of search engines like Google. The semantics of the simple search expression are as follows:

• Terms separated by whitespace are implicitly ANDed together.
• Terms may also be ORed with explicit use of the OR keyword.
• AND has higher precedence than OR.
• Terms may be excluded by prefixing with a – (minus sign) character. This means that the result set must not contain the excluded term.
• A term may be either a single word or a phrase delimited by double quotes (“"”).
• The entire text search expression (searchexp in the EBNF, above) must be delimited by single quotes (“'”).
• Within the searchexp literal instances of single quote (“'”), double quote (“"”) and hyphen (“-”) must be escaped with a backslash (“\”). Backslash itself must therefore also be escaped, ending up as double backslash (“\\”).

-/category

Example:

The following URL retrieves all objects of the jecars:User type from the/JeCARS/default/Users/ path. Without the parameter you will see a number of other objects e.g. P_* objects which are jecars:Permission objects.

HTTP

http://localhost:8080/cars/JeCARS/default/Users/-/User

alt

The alt option sets the type of output. The default alt setting is “atom”
Example using the alt=simple option.

HTTP

http://localhost:8080/cars/JeCARS/default/Users/-/User?alt=simple

When using a Client APP tool, use the alt=atomsvc option to provide the tool with a APP service document.

updated-min,updated-max

(TBS)

published-min,published-max

(TBS)

start-index

The start-index tag will result into two extra link tags in the atom output;
<link rel="previous" type="application/atom+xml" href="..."/>
<link rel="next" type="application/atom+xml" href="..."/>

max-results

The max-results tag will result into two extra link tags in the atom output;
<link rel="previous" type="application/atom+xml" href="..."/>
<link rel="next" type="application/atom+xml" href="..."/>

xpath

(TBS)

sql

The sql parameter will query the whole repository, so the path part of the URL won’t be used,
Please note that the sql parameter must be URL encoded.
e.g. to perform a;
SELECT * FROM jecars:root WHERE jecars:Type='READ'
The query returns all object who are part of JeCARS and have a property jecars:Type set to ‘READ’.

HTTP

http://localhost:8080/cars?sql=SELECT+*+FROM+jecars%3Aroot+WHERE+jecars%3AType%3D%27READ%27

It is important to encode the sql=’’ query string.

references

To retrieve the references to an object the references parameter can be used. Currently only one parameter is supported references=property, this will return the properties containing the reference.
Example:

To retrieve the references to the test1 user object;

HTTP

http://localhost:8080/cars/JeCARS/default/Users/Administrator?references=property

The resulting output (Atom format)

HTTP

200 OK

<?xml version="1.0"?>
<feed xmlns=http://www.w3.org/2005/Atom
      xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
      xmlns:jcr=http://www.jcp.org/jcr/1.0
      xmlns:jecars="http://jecars.org">
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Administrator</title>
<link rel="self" type="application/atom+xml"
        href="http://localhost:8080/cars/JeCARS/default/Users/Administrator"/>
<published>2007-05-29T10:53:08.296+02:00</published>
<updated>2007-05-29T10:53:08.296+02:00</updated>
<id>urn:uuid:...</id>
<category term='jecars:User'/>
<jecars:Password_crypt>.....</jecars:Password_crypt>
<jecars:Suspended>false</jecars:Suspended>
<jecars:Fullname>Administrator</jecars:Fullname>
</entry>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>jecars:GroupMembers</title>
<link rel="self" type="application/atom+xml"
href="
http://localhost:8080/cars/JeCARS/default/Groups/DefaultReadGroup/jecars:GroupMembers"/>
<published>2007-05-29T10:52:32.968+02:00</published>
<updated>2007-05-29T10:53:08.421+02:00</updated>
<id>%2FJeCARS%2Fdefault%2FGroups%2FDefaultReadGroup%2Fjecars%3AGroupMembers</id>
<category term='Reference'/>
</entry>
</feed>

The reference data is in the second entry block. The link rel=”self” contains the Property which contains a reference.

rights

(TBS)

childnodedefs

To retrieve the allowed child node types of an object the childnodedefs parameter can be used. Currently only one parameter is supported childnodedefs=property, this will return the properties containing the child node definitions.

Example:
To retrieve which nodetypes are allowed to be created under a Users object;

HTTP

http://localhost:8080/cars/JeCARS/default/Users?childnodedefs=property

The resulting output

HTTP

200 OK

<?xml version="1.0" encoding='utf-8'?>
<feed xmlns=http://www.w3.org/2005/Atom
xmlns:jcr=http://www.jcp.org/jcr/1.0
xmlns:jecars="http://jecars.org">
<title>Users</title>
<author><name>NLR</name></author>
<rights>(C) 2007, NLR</rights>
<link rel="self" type="application/atom+xml" href="http://localhost:8080/cars/JeCARS/default/Users"/>
<link rel="edit" type="application/atom+xml" href="http://localhost:8080/cars/JeCARS/default/Users"/>
<published>2007-08-03T14:51:45.921+02:00</published>
<updated>2007-08-03T14:51:45.921+02:00</updated>
<id>urn:uuid:...</id>
<category term='jecars:Users'/>
<jcr:created>2007-08-03T14:51:45.921+02:00</jcr:created>
<jcr:primaryType>jecars%3AUsers</jcr:primaryType>

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:jecars="http://jecars.org/">
<title>jecars:User</title>
<author><name>jecars.org</name></author>
<rights>(C) 2007</rights>
<link rel="alternate" type="application/atom+xml" href="http://localhost:8080/cars/JeCARS/default/Users/Administrator/jecars:Temp/childnodedefs_results_1186149836718/jecars:User"/>
<link rel="edit" type="application/atom+xml" href="http://localhost:8080/cars/JeCARS/default/Users/Administrator/jecars:Temp/childnodedefs_results_1186149836718/jecars:User"/>
<published>2007-08-03T16:03:56.718+02:00</published>
<updated>2007-08-03T16:03:56.718+02:00</updated>
<id>%2FJeCARS%2Fdefault%2FUsers%2FAdministrator%2Fjecars%3ATemp%2Fchildnodedefs_results_1186149836718%2Fjecars%3AUser</id>
<category term='jecars:root'/>
</entry>

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:jecars="http://jecars.nlr.nl/">
<title>jecars:permissionable</title>
<author><name>jecars.org</name></author>
<rights>(C) 2007</rights>
<link rel="alternate" type="application/atom+xml" href="http://localhost:8080/cars/JeCARS/default/Users/Administrator/jecars:Temp/childnodedefs_results_1186149836718/jecars:permissionable"/>
<link rel="edit" type="application/atom+xml" href="http://localhost:8080/cars/JeCARS/default/Users/Administrator/jecars:Temp/childnodedefs_results_1186149836718/jecars:permissionable"/>
<published>2007-08-03T16:03:56.718+02:00</published>
<updated>2007-08-03T16:03:56.718+02:00</updated>
<id>%2FJeCARS%2Fdefault%2FUsers%2FAdministrator%2Fjecars%3ATemp%2Fchildnodedefs_results_1186149836718%2Fjecars%3Apermissionable</id>
<category term='jecars:root'/>
</entry>

</feed>

The data is in the second entry block. The title’s of the entry are the nodetypes (encoded), in the example two types are allowed, jecars:permissionable and jecars:User.

deep

The deep parameter is used to choose between a deep or a shallow result. When deep=true the result will also include the children object from the given starting path.

e.g.

HTTP

http://localhost:8080/cars?deep=true

To get all objects available.

created-min, created-max

Use this parameter to query object within a certain creation date.

e.g.

HTTP

http://localhost:8080/cars?created-min=2007-07-25T09:00:00.000%2B02:00

The ‘%2B’ (‘+’) is necessary when used in a browser.

Use the deep=true parameter to search through the complete tree.

HTTP

http://localhost:8080/cars?created-min=2007-07-25T09:00:00.000%2B02:00&deep=true

Or use the "now" option;

e.g.

HTTP

http://localhost:8080/cars?created-min=now-2h&deep=true

To get the objects created in the last 2 hours

keywords

(TBS)

this-node

(TBS)

version-history

(TBS)

orderby & orderbytype

HTTP

http://localhost:8080/cars?orderbycreated-min=now-2h&deep=true

POST

HTTP POST calls are used to create resources. However it is also possible to generate POST messages with the GET HTTP call. As parameter the "X-HTTP-Method-Override=POST" must be added to the GET call.

Creation of nodes

To create a new entry, send a POST request, and supply a new entry;
A simple example to create a user;

HTTP

POST http://localhost:8080/cars/default/Users/testUser1

<?xml version="1.0"?>
<entry xmlns=”http://www.w3.org/2005/Atom”
xmlns:jecars=”http://jecars.org”>
<jecars:Fullname>Test User 1</jecars:Fullname>
<jecars:Password_crypt>secret</jecars:Password_crypt>
</entry>

The server response;

HTTP

201 CREATED
Location: <url to the created object (=link rel=”self”)

<?xml version="1.0"?>
<entry xmlns=”http://www.w3.org/2005/Atom”
xmlns:jecars=”http://jecars.org/”>
<title>testUser1</title>
<link rel="self" type="application/atom+xml"
href="http://localhost:8080/cars/JeCARS/default/Users/testUser1"/>
<published>2007-05-15T13:43:38.015+02:00</published>
<updated>2007-05-15T13:43:38.015+02:00</updated>
<id>urn:uuid:xxxxx-xxxx-xxx-xx</id>
<category term='jecars:User'/>
<jecars:Password_crypt>.....</jecars:Password_crypt>
<jecars:Fullname>Test User 1</jecars:Fullname>
</entry>

On default the response will be in atom format, using the alt= option it is possible to get another type of response.

In this case the system knows what kind of object type must be created. (jecars:User)

The <category term=’....’> tag can be used to define the object type.

HTTP

POST http://localhost:8080/cars/default/Users/testUser1

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<category term=’jecars:User’/>
<jecars:Fullname>Test User 1</jecars:Fullname>
<jecars:Password_crypt>geheim</jecars:Password_crypt>
</entry>

It is possible that the object created will get a different ID (URL) then ask for. The client should take the link given in the <link rel=”self”.... tag as the created id.

Creating an object using copy

To create a new object while using an other object a reference the <link rel=’via’ href=’....’/> tag can be used. It depends on the parent object how this reference is being used to create the new object.

HTTP

POST http://localhost:8080/cars/JeCARS/default/Users/newUser

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<link rel=’via’ href=’http://localhost:8080/cars/JeCARS/default/Users/testUser1’/>
</entry>

Please note that not all nodetypes support the creation using copy option.

Creation using the slug HTTP header

As described in the Atom Publishing Protocol reference, is it also possible to use the slug http header to indicate the new name of the object.

A simple example to create a user;

HTTP

POST http://localhost:8080/cars/default/Users
Slug: testUsers1

<?xml version="1.0"?>
<entry xmlns=”http://www.w3.org/2005/Atom”
xmlns:jecars=”http://jecars.org”>
<jecars:Fullname>Test User 1</jecars:Fullname>
<jecars:Password_crypt>secret</jecars:Password_crypt>
</entry>

Parameters as URL parameters

It is also possible to send the parameters using the URL parameters (?..=..&..=..).

Parameters

The standard POST parameters are summarized in the following table. All parameter values need to be URL encoded.

Parameter

Meaning

Notes

alt

Alternative representation type

If you don't specify an alt parameter, the service returns an Atom feed. This is equivalent to alt=atom.
alt=simple returns an simple text result.

Error codes

The creation is only succesful when a 201 OBJECT CREATED reply is received.

When the object already existed a 1300 ENTITY EXISTS error is returned. When the parent node supports “same-name sibblings” the new object will have a index number.

PUT

HTTP PUT calls are used to update resources. However it is also possible to generate PUT messages with the GET HTTP call. As parameter the "X-HTTP-Method-Override=PUT" must be added to the GET call.

Node updating

To update an existing entry, use the PUT HTTP request.

HTTP

PUT http://localhost:8080/cars/JeCARS/default/Users/testUser1

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<jecars:Fullname>New User name</jecars:Fullname>
</entry>

The server response

HTTP

200 OK

It is also possible to update the node name (ID) itself. The jecars:title tag shou