
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 shou