
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 |
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 |
|
|
User id |
|
|
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=yourAuthValueIt is also possible to supply the
Auth value as URL parameter. Use GOOGLELOGIN_AUTH=yourAuthValue parameter.
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 |
|
200 OK <?xml version="1.0" encoding='utf-8'?> <id>%2FJeCARS%2Fdefault%2FUsers</id> <link rel="edit" type="application/atom+xml" href="http://localhost:8080/cars/JeCARS/default/Users/Superuser"/> <link rel="alternate" type="application/atom+xml" href="http://localhost:8080/cars/JeCARS/default/Users/Administrator"/> |
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 |
|
|
-/category |
Category filter |
|
|
alt |
Alternative representation type |
|
|
updated-min, updated-max |
Bounds on the entry update date |
|
|
published-min, published-max |
Bounds on the entry publication date |
|
|
start-index |
1-based index of the first result to be retrieved |
|
|
max-results |
Maximum number of results to be retrieved |
|
|
xpath |
Xpath search |
|
|
sql |
SQL search |
|
|
references |
Retrieve the references of this object |
|
|
rights |
Retrieve the access rights of this object |
|
|
childnodedefs |
Retrieve the allowed child node types of this object |
|
|
deep |
Include the children in the search. |
|
|
created-min, created-max |
Bounds on the entry create date |
|
|
keywords |
Search on keywords. |
|
|
this-node |
How to render “this node” |
|
| version-history |
Show the version history of this object |
|
| orderby | Order the results |
|
| orderbytype | Ordering specifier |
|
|
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:
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 |
|
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.
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="..."/>
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="..."/>
(TBS)
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.
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 |
1 |
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.
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 |
1 |
http://localhost:8080/cars/JeCARS/default/Users?childnodedefs=property
|
|
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.
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 |
1 |
Use this parameter to query object within
a certain
creation date.
e.g.
|
HTTP |
1 |
http://localhost:8080/cars?created-min=2007-07-25T09:00:00.000%2B02:00 |
|
HTTP |
1 |
http://localhost:8080/cars?created-min=2007-07-25T09:00:00.000%2B02:00&deep=true |
|
HTTP |
1 |
(TBS)
(TBS)
(TBS)
|
HTTP |
1 |
http://localhost:8080/cars?orderbycreated-min=now-2h&deep=true |
|
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.
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.
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> |
It is also possible to send the parameters using the URL parameters (?..=..&..=..).
|
Parameter |
Meaning |
Notes |
|
alt |
Alternative representation type |
|
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.
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 should be used to do so.
|
HTTP |
|
PUT http://localhost:8080/cars/JeCARS/default/Users/testUser1 <?xml version="1.0"?> <entry xmlns="http://www.w3.org/2005/Atom"> <title>NewName</title> </entry> |
Object can have multivalue properties, updating them
is a bit different.
Example:
Add an user to a group object. A jecars:Group object has a multivalue jecars:GroupMembers property field which contains the UUID’s of the members.|
HTTP |
|
PUT http://localhost:8080/cars/JeCARS/default/Group/theGroup <?xml version="1.0"?> <entry xmlns="http://www.w3.org/2005/Atom"> <jecars:GroupMembers>+/JeCARS/default/Users/testUser1</jecars:GroupMembers> </entry> |
The first character of the multivalue property has a special meaning see the following table;
|
Parameter |
Meaning |
Notes |
|
+ |
Add the value |
+ = %2B (URL encoded) |
|
- |
Remove the value |
|
|
~ |
Remove all values |
No further parameters are neccessary <jecars:GroupMembers>~</jecars:GroupMembers> |
|
HTTP |
|
DELETE
http://localhost:8080/cars/JeCARS/default/Users/testUser1 |
The server response;
|
HTTP |
|
200 OK <?xml version="1.0"?> <entry xmlns="http://www.w3.org/2005/Atom"> <link rel="alternate" type="application/atom+xml" href="http://test.nl/JeCARS/default/Users/testUser1"/> </entry> |
(TBS)
The standard delete parameters are summarized in the following table. All parameter values need to be URL encoded.
|
Parameter |
Meaning |
Notes |
|
namePattern |
Match the objects using a name pattern. |
Deletes all child nodes of this node that match namePattern. The pattern may be a full name or a partial name with one or more wildcard characters ("*"), or a disjunction (using the "|" character to represent logical OR) of these. For example, "jcr:* | myapp:report | my doc" would delete child nodes that are either called 'myapp:report', begin with the prefix 'jcr:' or are called 'my doc'. Note that leading and trailing whitespace around a disjunct is ignored, but whitespace within a disjunct forms part of the pattern to be matched. The EBNF for namePattern is:
namePattern ::=
disjunct {'|' disjunct} The pattern is matched against the names (not the paths) of the immediate child nodes of this node. If this node has no matching child nodes, then nothing is being deleted |
|
force |
Force the deletion of the object |
When an object cannot being deleted the force parameter when set on true will make some extra options possible
|
|
trashcan |
Use the trashcan |
(NI) The objects are not deleted but moved (with a mixin nodetype) to the trashcan. If the trashcan parameter is set to true then the default trashcan is used (/JeCARS/jecars:Trashcans/jecars:General). Otherwise the parameter should point to a jecars:Trashcan object.
|
The deletion is only succesful when a 200
OK reply is received.
A 403
FORBIDDEN error is returned if the
object cannot being deleted. Possible reasons;
The following table describes what various HTTP status codes mean in the context of JeCARS.
|
Code |
Explanation |
|
200 OK |
No error. |
|
201 CREATED |
Creation of a resource was successful. |
|
304 NOT MODIFIED |
The resource hasn't changed since the time specified in the requests If-Modified-Since header. (NI) |
|
400 BAD REQUEST |
Invalid request URI or header, or unsupported nonstandard parameter. (NI) |
|
401 UNAUTHORIZED |
Authorization required. |
|
403 FORBIDDEN |
Unsupported standard parameter, or authentication or authorization failed. |
|
404 NOT FOUND |
Resource (such as a feed or entry) not found. |
|
406 HTTP_NOT_ACCEPTABLE |
Constraint violation exception |
|
409 CONFLICT |
Specified version number doesn't match resource's latest version number. (NI) |
|
500 INTERNAL SERVER ERROR |
Internal error. This is the default code that is used for all unrecognized errors. |
|
1300 ENTITY EXISTS |
The request instructs JeCARS to create an entity that already exists |
The property types which names are ending with _crypt are being encrypted when stored. When such a property is being retrieved the encrypted value is returned. The property value is being encrypted using a SHA-1 (Secure Hash Algorithm 1) encryption method.
Version control
|
Parameter |
Meaning |
Notes |
|
vcs |
Which version control system to use. |
Defaults to 'jcr' |
|
vcs-cmd |
Version control command |
|
|
vcs-label |
Version label |
|