API Docs

Introduction

It's all about Resources

Rollcall's API is RESTful. It's all about resources on which you can perform the four core CRUD actions (Create, Retrieve, Update, Delete).

Resources managed by Rollcall:

Users
Groups
Sessions
Curnits
Runs

There are also Metadata and GroupMemberships, but you probably won't be doing anything with those directly.

Each Resource has its own URL

Each resource has its own URL. For example a User with ID 123 might be under http://your.server.com/users/123.xml while the list of all Users would be under http://your.server.com/users.xml.

Create, Retrieve, Update, and Destroy

To perform an action on a resource or collection of resources, you issue an HTTP request with the appropriate HTTP method to the resource or collection URL. For example to delete the User with ID 123 you would send and HTTP DELETE request to http://your.server.com/users/123.

The four HTTP CRUD methods are:

GET: Retrieves the resource or collection of resources from the given URL. For example, GET /users would retrieve the list of all Users, while GET /users would retrieve only the user with ID 5).
POST: Creates a new resource. For example, POST /users would create a new User. The data sent in the POST request would be used to fill in the User's properties.
PUT: Updates an existing resource. For example, PUT /users/5 would update the User with id 5. The data sent in the PUT request would be used to update the User's properties.
DELETE: Deletes an existing resource. For example, DELTE /users/5 would delete the User with id 5.

Formats: XML, JSON, and HTML

You can specify the format of the response by adding .xml or .json or .html to the URL. GET /users/5.xml will return data in XML format and GET /users/5.json will return in JSON.

If you don't specify an extension in the URL (e.g. `GET /users/5.xml), Rollcall will try to automatically determine the best format depending on the headers in your HTTP request. Generally a regular web browser request will get you HTML, while an AJAX request will get you XML.

The API

### Users

<tr>
  <td><tt>POST</tt> <strong><tt>/users</tt></strong></td>
  <td>Create a new user</td>
  <td>

  {
    user: {
      username: "jsmith",
      password: "topsecret",
      display_name: "John Smith",
      kind: "Student" || "Instructor" || "Admin"
    }
  }

  </td>
</tr>

<tr>
  <td><tt>GET</tt> <strong><tt>/users/1</tt></strong></td>
  <td>Retrieve the user with ID <tt>1</tt></td>
  <td />
</tr>

<tr>
  <td><tt>PUT</tt> <strong><tt>/users/1</tt></strong></td>
  <td>Update user with ID <tt>1</tt></td>
  <td>

  {
    user: {
      password: "topsecret",
      display_name: "John Smith",
      kind: "Student" || "Instructor" || "Admin"
    }
  }

  </td>
</tr>

<tr>
  <td><tt>DELETE</tt> <strong><tt>/users/1</tt></strong></td>
  <td>Delete user with ID <tt>1</tt></td>
  <td />
</tr>

Method & URL	Description	Parameters
`GET` `/users`	Retrieve the list of all users

### Groups

<tr>
  <td><tt>POST</tt> <strong><tt>/groups</tt></strong></td>
  <td>Create a new group</td>
  <td>

  {
    group: {
      name: "My Group",
      run_id: 123
    }
  }

  </td>
</tr>

<tr>
  <td><tt>GET</tt> <strong><tt>/groups/1</tt></strong></td>
  <td>Retrieve the group with ID <tt>1</tt></td>
  <td />
</tr>

<tr>
  <td><tt>PUT</tt> <strong><tt>/groups/1</tt></strong></td>
  <td>Update group with ID <tt>1</tt></td>
  <td>

  {
    group: {
      name: "My Group",
      run_id: 123
    }
  }

  </td>
</tr>

<tr>
  <td><tt>PUT</tt> <strong><tt>/groups/1/add_member</tt></strong></td>
  <td>Add a new member to the group with ID <tt>1</tt></td>
  <td>

  {
    member: {
      type: "User" || "Group",
      id: 123 /* ID of the User or Group you're adding */
    }
  }

  </td>
</tr>

<tr>
  <td><tt>PUT</tt>&nbsp;<strong><tt>/groups/1/remove_member</tt></strong></td>
  <td>Remove a member from group with ID <tt>1</tt></td>
  <td>

  {
    member: {
      type: "User" || "Group",
      id: 123 /* ID of the User or Group you're removing */
    }
  }

  </td>
</tr>

<tr>
  <td><tt>DELETE</tt> <strong><tt>/groups/1</tt></strong></td>
  <td>Delete group with ID <tt>1</tt></td>
  <td />
</tr>

Method & URL	Description	Parameters
`GET` `/groups`	Retrieve the list of all groups

### Sessions

<tr>
  <td><tt>POST</tt> <strong><tt>/login</tt></strong></td>
  <td>Start a new session (i.e. log in as a user)</td>
  <td>

  {
    username: "jsmith",
    password: "topsecret"
  }

  </td>
</tr>

<tr>
  <td><tt>GET</tt> <strong><tt>/login/validate_token/mzukowski/123abc</tt></strong></td>
  <td>
    Checks whether authentication token <tt>123abc</tt> is valid for username <tt>mzukowski</tt>.
    This is used for single-sign-on functionality. When a user logs in they're given an auth token that
    can be used to carry their auth session from service to service.
  </td>
  <td />
</tr>

<tr>
  <td><tt>DELETE</tt> <strong><tt>/sessions/1</tt></strong></td>
  <td>Close the session with ID <tt>1</tt></td>
  <td />
</tr>

Method & URL	Description	Parameters
`GET` `/sessions`	Retrieve the list of all open sessions

Logging in

You "log in" a user by POSTing their username and password to the /login URL:

POST /login.xml POST Parameters:

{
  username: jsmith
  password: topsecret
}

If the username or password is invalid, you'll get a response with status code 401 (Unauthorized). If the credentials are correct, Rollcall creates a Session resource for the user and returns an XML or JSON representation of the Session (/login.xml for XML, /login.json for JSON) with response code 200:

XML Response	JSON Response
```xml 2010-10-29T20:36:21Z 8e6s8xw3rynf93j45pwyq0bjzc0pvygqcd2m 2010-10-29T20:36:21Z 25 1 ```	```js { session: { created_at: "2010-10-29T20:36:21Z", updated_at: "2010-10-29T20:36:21Z", token: "8e6s8xw3rynf93j45pwyq0bjzc0pvygqcd2m", id: 25, user_id: 1 } } ```

You'll want to keep the token (for example in a session cookie) so that you can use it later to authenticate the user on a new service without having to re-enter their credentials.

For example, if you want to validate the token given in the response above, you would:

POST /login/validate_token/jsmith/8e6s8xw3rynf93j45pwyq0bjzc0pvygqcd2m

If the username and token match an open session (i.e. the user is logged in and has an active session with the given token), you'll get a response with status 200 like this:

XML Response	JSON Response
```xml 2010-11-12T22:37:00Z 8e6s8xw3rynf93j45pwyq0bjzc0pvygqcd2m 2010-11-12T22:37:00Z 25 1 Student 2010-11-12T22:36:53Z 2010-11-12T22:36:53Z jsmith 1 John Smith topsecret ```	```js { "session": { "created_at": "2010-11-12T22:37:00Z", "updated_at": "2010-11-12T22:37:00Z", "token": "ko0s7ky5vq00pfh3q0wzlpwzfhxu9fvtil48", "user": { "kind": "Student", "created_at": "2010-11-12T22:36:53Z", "updated_at": "2010-11-12T22:36:53Z", "username": "test", "id": 129, "display_name": "Test Test", "password": "test2" }, "id": 26, "user_id": 129 } } ```

### Curnits

<tr>
  <td><tt>POST</tt> <strong><tt>/curnits</tt></strong></td>
  <td>Create a new curnit</td>
  <td>

  {
    curnit: {
      name: "My Curnit"
    }
  }

  </td>
</tr>

<tr>
  <td><tt>GET</tt> <strong><tt>/curnits/1</tt></strong></td>
  <td>Retrieve the curnit with ID <tt>1</tt></td>
  <td />
</tr>

<tr>
  <td><tt>PUT</tt> <strong><tt>/curnits/1</tt></strong></td>
  <td>Update curnit with ID <tt>1</tt></td>
  <td>

  {
    curnit: {
      name: "My Curnit"
    }
  }

  </td>
</tr>

<tr>
  <td><tt>DELETE</tt> <strong><tt>/curnits/1</tt></strong></td>
  <td>Delete curnit with ID <tt>1</tt></td>
  <td />
</tr>

Method & URL	Description	Parameters
`GET` `/curnits`	Retrieve the list of all curnits

### Runs

<tr>
  <td><tt>POST</tt> <strong><tt>/runs</tt></strong></td>
  <td>Create a new run</td>
  <td>

  {
    curnit: {
      name: "My Run",
      curnit_id: 123
    }
  }

  </td>
</tr>

<tr>
  <td><tt>GET</tt> <strong><tt>/runs/1</tt></strong></td>
  <td>Retrieve the run with ID <tt>1</tt></td>
  <td />
</tr>

<tr>
  <td><tt>GET</tt> <strong><tt>/curnits/2/runs</tt></strong></td>
  <td>Retrieve all the runs under curnit with ID <tt>1</tt></td>
  <td />
</tr>

<tr>
  <td><tt>PUT</tt> <strong><tt>/runs/1</tt></strong></td>
  <td>Update run with ID <tt>1</tt></td>
  <td>

  {
    curnit: {
      name: "My Run",
      curnit_id: 123
    }
  }

  </td>
</tr>

<tr>
  <td><tt>DELETE</tt> <strong><tt>/runs/1</tt></strong></td>
  <td>Delete run with ID <tt>1</tt></td>
  <td />
</tr>

Method & URL	Description
`GET` `/runs`	Retrieve the list of all runs

Examples

PHP: Zend_Rest_Client Examples

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API Docs

API Docs

Introduction

It's all about Resources

Each Resource has its own URL

Create, Retrieve, Update, and Destroy

Formats: XML, JSON, and HTML

The API

Logging in

Examples

Clone this wiki locally