Skip to content

API Docs

Jump to bottom Edit New page
zuk edited this page Oct 24, 2011 · 71 revisions

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:

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>`GET` <strong>`/users?run_id=8`</strong></td>
  <td>Retrieve the list of users in groups with the given run_id</td>
  <td />
</tr>

<tr>
  <td>`POST` <strong>`/users`</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>`GET` <strong>`/users/1`</strong></td>
  <td>Retrieve the user with ID `1`</td>
  <td />
</tr>

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

  {
    user: {
      password: "topsecret",
      display_name: "John Smith",
      kind: "Student" || "Instructor" || "Admin"
    }
  }
  </td>
</tr>

<tr>
  <td>`DELETE` <strong>`/users/1`</strong></td>
  <td>Delete user with ID `1`</td>
  <td />
</tr>
Method and Example URL Description Parameters
`GET` `/users` Retrieve the list of all users

Sample responses

GET /users/1

XML Response JSON Response
```xml Student 2010-11-12T22:36:53Z 2010-11-12T22:36:53Z test 129 Test Test test2 ``` ```js { "user": { "kind": "Student", "created_at": "2010-11-12T22:36:53Z", "updated_at": "2010-11-12T22:36:53Z", "metadata": {}, "username": "test", "id": 129, "display_name": "Test Test", "password": "test2" } } ```

GET /users

XML Response JSON Response
```xml Student 2010-09-24T19:13:56Z 2010-09-24T19:13:56Z test-user-45102 1 Test User 45102 testtest45102 bar 123 Student 2010-09-24T19:13:56Z 2010-09-24T19:13:56Z test-user-49090 2 Test User 49090 testtest49090 bar 123 ``` ```js [ { "user": { "kind": "Student", "created_at": "2010-09-24T19:13:56Z", "updated_at": "2010-09-24T19:13:56Z", "metadata": { "foo": "bar", "test":"123" }, "username": "test-user-45102", "id": 1, "display_name": "Test User 45102", "password": "testtest45102" } }, { "user": { "kind": "Student", "created_at": "2010-09-24T19:13:56Z", "updated_at": "2010-09-24T19:13:56Z", "metadata": { "foo": "bar", "test":"123" }, "username": "test-user-49090", "id": 2, "display_name": "Test User 49090", "password": "testtest49090" } } ] ```
## Groups 
<tr>
  <td>`POST` <strong>`/groups`</strong></td>
  <td>Create a new group</td>
  <td>

  {
    group: {
      name: "My Group",
      run_id: 123
    }
  }
  </td>
</tr>

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

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

  {
    group: {
      name: "My Group",
      run_id: 123
    }
  }
  </td>
</tr>

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

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

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

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

<tr>
  <td>`DELETE` <strong>`/groups/1`</strong></td>
  <td>Delete group with ID `1`</td>
  <td />
</tr>
Method and Example URL Description Parameters
`GET` `/groups` Retrieve the list of all groups
### Sessions 
<tr>
  <td>`POST` <strong>`/login`</strong></td>
  <td>Start a new session (i.e. log in as a user)</td>
  <td>

  {
    session: {
      login: "jsmith",
      password: "topsecret" 
    }
  }
  </td>
</tr>

<tr>
  <td>`GET` <strong>`/login/validate_token/123abc`</strong></td>
  <td>
    Checks whether authentication token `123abc` is valid.
    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>`DELETE` <strong>`/sessions/1`</strong></td>
  <td>Close the session with ID `1`</td>
  <td />
</tr>
Method and Example URL Description Parameters
`GET` `/sessions` Retrieve the list of all open sessions
#### Logging in

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

POST /login.xml

Parameters:

  {
    session: {
      login: "jsmith",
      password: "topsecret" 
    }
  }

If the login 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 do not correspond to a valid session, you'll get a 404 (Not Found) or 400 (Bad Request) response. 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": "8e6s8xw3rynf93j45pwyq0bjzc0pvygqcd2m", "user": { "kind": "Student", "created_at": "2010-11-12T22:36:53Z", "updated_at": "2010-11-12T22:36:53Z", "username": "jsmith", "id": 1, "display_name": "John Smith", "password": "topsecret" }, "id": 26, "user_id": 129 } } ```
## Curnits 
<tr>
  <td>`POST` <strong>`/curnits`</strong></td>
  <td>Create a new curnit</td>
  <td>

  {
    curnit: {
      name: "My Curnit"
    }
  }
  </td>
</tr>

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

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

  {
    curnit: {
      name: "My Curnit"
    }
  }
  </td>
</tr>

<tr>
  <td>`DELETE` <strong>`/curnits/1`</strong></td>
  <td>Delete curnit with ID `1`</td>
  <td />
</tr>
Method and Example URL Description Parameters
`GET` `/curnits` Retrieve the list of all curnits
## Runs 
<tr>
  <td>`POST` <strong>`/runs`</strong></td>
  <td>Create a new run</td>
  <td>

  {
    curnit: {
      name: "My Run",
      curnit_id: 123
    }
  }
  </td>
</tr>

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

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

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

  {
    curnit: {
      name: "My Run",
      curnit_id: 123
    }
  }
  </td>
</tr>

<tr>
  <td>`DELETE` <strong>`/runs/1`</strong></td>
  <td>Delete run with ID `1`</td>
  <td />
</tr>
Method and Example URL Description
`GET` `/runs` Retrieve the list of all runs

Examples

Add a custom footer
Add a custom sidebar
Clone this wiki locally