Release 1.0.0

Version 1.0.0 is the initial release. This is the first version of the usage document.

Interface

User List

URI /user
Description List all of the users.
URI Parameters
HTTP Methods * GET - Returns a list of users
* POST - Adds a user. For the XML specification,
refer to the user information resource.

Example of a GET request:

  http://localhost:8080/exampleRest/user/

Example of XML response:

  <?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
  <users>
    <user key="admin">
      <link rel="self" type="text/xml" href="http://localhost:8080/exampleRest/user/admin"/>
      <link ref="edit" href="http://localhost:8080/exampleRest/user/admin"/>
      <id>1</id>
      <created>2009-11-04T22:23:46Z</created>
      <username>admin</username>
      <givenName>Admin</givenName>
      <familyName>User</familyName>
    </user>
    <user key="bob">
      <link rel="self" type="text/xml" href="http://localhost:8080/exampleRest/user/foo"/>
      <link ref="edit" href="http://localhost:8080/exampleRest/user/foo"/>
      <id>2</id>
      <created>2009-11-04T22:23:46Z</created>
      <username>bob</username>
      <givenName>Bob</givenName>
      <familyName>Smith</familyName>
    </user>
  </users>

Elements in the response:

Element Description Attributes
users A list of users.
Refer to the section on user information below
for the elements describing each user.

User Information

URI /user/USER-KEY
where USER-KEY is the username
Description Retrieves or updates information about a specific
user and allows deletion of the user.
URI Parameters
HTTP Methods * GET - Returns information about the given user.
* PUT - Updates the user details.
* DELETE - Removes the user.

Here is an example of a request for information on user 'bob'.

  http://localhost:8080/exampleRest/user/bob

The following curl request deletes the user 'bob', using basic authentication where the username and password are both 'admin'.

  curl -X DELETE http://localhost:8080/exampleRest/user/bob -u admin:admin

Example of XML response giving user information:

  <?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
  <user key="bob">
    <link rel="self" type="text/xml" href="http://localhost:8080/exampleRest/user/foo"/>
    <link ref="edit" href="http://localhost:8080/exampleRest/user/foo"/>
    <id>2</id>
    <created>2009-11-04T22:23:46Z</created>
    <username>bob</username>
    <givenName>Bob</givenName>
    <familyName>Smith</familyName>
  </user>

Example of data file to create a user:

  file: createUser.xml
  <?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
  <user key="bob">
    <username>bob</username>
    <givenName>Bob</givenName>
    <familyName>Smith</familyName>
  </user>

The following curl request create the user 'bob', using basic authentication where the username and password are both 'admin' and using the data file createUser.xml.

  curl -X POST -d @createUser.xml -H "Content-Type: text/xml" http://localhost:8080/exampleRest/user/

Elements in the response:

Element Description Attributes
user A user.
id Unique identifier.
created Date user created. Format:
"yyyy-MM-dd'T'HH:mm:ss'Z'"
updated Date user last updated. Format:
"yyyy-MM-dd'T'HH:mm:ss'Z'"
username The user's username.
givenName The user's first name.
additionalName The user's middle name.
familyName The user's last name.
email The user's email address.

User's Password

URI /user/USER-KEY/password
Description List all of the users.
URI Parameters
HTTP Methods * PUT - Update the user's password.

Example of a file to update a password. The file contains the new plain text password:

  file: password.txt
  newP@$$word

Example of a curl command to update a user's password using the new plain text password defined in the file "password.txt". Basic authentication is used, where the username and password are both 'admin'. This would require that the user 'admin' be in the 'admin' group to change someone else's password. The user 'bob' could change his own password using basic authentication where the username is 'bob' and the password is 'oldP@$$word'.

  curl -X PUT -d @password.txt http://localhost:8080/exampleRest/user/bob/password -u admin:admin

Group List

URI /group
Description List all of the groups.
URI Parameters
HTTP Methods * GET - Returns a list of groups
* POST - Adds a group. For the XML specification,
refer to the group information resource.

Example of a GET request:

  http://localhost:8080/exampleRest/group/

Example of XML response:

  <?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
  <group>
    <group key="admin">
      <link rel="self" type="text/xml" href="http://localhost:8080/exampleRest/group/admin"/>
      <link ref="edit" href="http://localhost:8080/exampleRest/group/admin"/>
      <id>0</id>
      <created>2009-11-04T22:23:46Z</created>
      <name>admin</username>
      <description>Adminstrator</description>
    </group>
    <group key="editor">
      <link rel="self" type="text/xml" href="http://localhost:8080/exampleRest/group/editor"/>
      <link ref="edit" href="http://localhost:8080/exampleRest/group/editor"/>
      <id>2</id>
      <created>2009-11-04T22:23:46Z</created>
      <name>editor</username>
      <description>Copy editors.</description>
    </group>
  </group>

Elements in the response:

Element Description Attributes
groups A list of groups.
Refer to the section on group information below
for the elements describing each group

Group Information

URI /group/GROUP-KEY
where GROUP-KEY is the group name
Description Retrieves or updates information about a specific
group and allows deletion of the group.
URI Parameters
HTTP Methods * GET - Returns information about the given group.
* PUT - Updates the group details.
* DELETE - Removes the group.

Here is an example of a request for information on group 'editor'.

  http://localhost:8080/exampleRest/group/editor

The following curl request deletes the group 'editor', using basic authentication where the username and password are both 'admin'.

  curl -X DELETE http://localhost:8080/exampleRest/group/editor -u admin:admin

Example of XML response giving user information:

  <?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
  <group key="editor">
    <link rel="self" type="text/xml" href="http://localhost:8080/exampleRest/group/editor"/>
    <link ref="edit" href="http://localhost:8080/exampleRest/group/editor"/>
    <id>2</id>
    <created>2009-11-04T22:23:46Z</created>
    <name>editor</username>
    <description>Copy editors.</description>
  </group>

Elements in the response:

Element Description Attributes
group A group.
id Unique identifier.
created Date group created. Format:
"yyyy-MM-dd'T'HH:mm:ss'Z'"
updated Date group last updated. Format:
"yyyy-MM-dd'T'HH:mm:ss'Z'"
name The group's name.
description The group's description.

Group Members

URI /group/GROUP-KEY/user/
where GROUP-KEY is the group name
Description Retrieves list of users who are members of the group
URI Parameters
HTTP Methods * GET - Returns information about the given group.
* POST - Add a user to the group.

Here is an example of a request for user members of the group 'editor'.

  http://localhost:8080/exampleRest/group/editor/user/

Example of data file to create a user:

  file: member.txt
  bob

The following curl request add the user 'bob', using basic authentication where the username and password are both 'admin'.

  curl -X POST -d @member.txt -H "Content-Type: text/plain"
  http://localhost:8080/exampleRest/group/editor/user/ -u admin:admin

Example of XML response giving user information:

  <users>
    <user key="admin">
      <link rel="self" type="text/xml" href="http://localhost:8080/exampleRest/user/admin"/>
      <link ref="edit" href="http://localhost:8080/exampleRest/user/admin"/>
      <id>1</id>
      <created>2009-11-04T22:23:46Z</created>
      <username>admin</username>
      <givenName>Admin</givenName>
      <familyName>User</familyName>
    </user>
    <user key="bob">
      <link rel="self" type="text/xml" href="http://localhost:8080/exampleRest/user/foo"/>
      <link ref="edit" href="http://localhost:8080/exampleRest/user/foo"/>
      <id>2</id>
      <created>2009-11-04T22:23:46Z</created>
      <username>bob</username>
      <givenName>Bob</givenName>
      <familyName>Smith</familyName>
    </user>
  </users>

Elements in the response:

Element Description Attributes
users A list of users.
Refer to the section on user information above
for the elements describing each user.

Group Member

URI /group/GROUP-KEY/user/USER-KEY
where GROUP-KEY is the group name
and USER-KEY is the username
Description Removes the user from the group
URI Parameters
HTTP Methods * DELETE - Remove a user from a group.

The following curl request removes the user 'bob', using basic authentication where the username and password are both 'admin'.

  curl -X DELETE http://localhost:8080/exampleRest/group/editor/user/bob -u admin:admin

Resources