Skip to content

Class Manipulation

Jump to bottom
joshuaselsky edited this page Mar 20, 2012 · 16 revisions

Class Create

What does it do?

Creates classes (groups of users).

URI

class/create

Access Rules

Only admins may create classes.

Input Parameters

  • (r) auth_token = The authentication token.
  • (r) client = A string representing the client.
  • (r) class_urn = The new class' URN.
  • (r) class_name = The new class' name.
  • (o) description = An optional description for the class.

Example POST

POST /app/class/create HTTP/1.1
 Host: dev.ohmage.org
 Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
 Content-Length: byte-length-of-content
 Content-Type: application/x-www-form-urlencoded
 
  auth_token=abcfcd36-ab25-4494-8434-7798cb1d718e
  &class_urn=urn:class:new
  &class_name=New class.
  &client=ohmage-js

Output Format

Success

{
    "result" : "success"
}

Failure

See the error page for a description of error codes and their associated descriptions.

Back to Top

Class Read

What does it do?

Returns class names, descriptions and users for one or many classes.

URI

class/read

Access Rules

Admins can read all class information in the system. Privileged users can see all class data for classes to which they belong. Restricted users can see all class data, excluding logins, for classes to which they belong.

Input Parameters

  • (r) auth_token = The authentication token. May also be set using the Set-Cookie header.
  • (r) client = A string representing the client.
  • (r) class_urn_list = A comma-separated list of class URNs.

Example POST

POST /app/class/read HTTP/1.1
 Host: dev.ohmage.org
 Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
 Content-Length: byte-length-of-content
 Content-Type: application/x-www-form-urlencoded
 
  auth_token=abcfcd36-ab25-4494-8434-7798cb1d718e
  &class_urn=urn:class:los_angeles
  &client=ohmage-MWoC

Output Format

Success

{
    "result":"success",
    "data": {
        "urn:class:user:is:privileged" : {
        "name" : "AndWellness",
        "description" : "Ohmage, formerly known as AndWellness and intermittently known as Mobilize and incorrectly pronounced as homage."
         "users" : {
            "joe.shmoe" : "privileged",
            "other.guy" : "restricted",
             "some.one" : "restricted",
             ...
         }
     },
     "urn:class:user:is:restricted" : {
         "name" : "Other",
         "description" : "",
         "users" : {
             "this.guy" : "",
             "joe.shmoe" : "",
             ...
         }
     }
 }

Failure

See the error page for a description of error codes and their associated descriptions.

Back to Top

Class Roster Read

What does it do?

Returns a CSV text file containing newline-separated lists of users associated with the provided class URNs.

URI

class/roster/read

Access Rules

The user must be an admin or must be privileged in each of the classes they are attempting to read.

Input Parameters

  • (r) auth_token = The authentication token. May also be set using the Set-Cookie header.
  • (r) client = A string representing the client.
  • (r) class_urn_list = A comma-separated list of class URNs.

Example POST

POST /app/class/read HTTP/1.1
 Host: dev.ohmage.org
 Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
 Content-Length: byte-length-of-content
 Content-Type: application/x-www-form-urlencoded
 
  auth_token=abcfcd36-ab25-4494-8434-7798cb1d718e
  &class_urn=urn:class:los_angeles
  &client=ohmage-MWoC

Output Format

Success

<class id>,<first username>,<first user's class role>
<class id>,<second username>,<second user's class role>
<second class id>,<third username>,<third user's class role>
<second class id>,<first username>,<first user's second class role>
...

Failure

See the error page for a description of error codes and their associated descriptions.

Back to Top

Class Search

What does it do?

This API is designed for administrators to allow them to read all of the information about any class. If none of the optional parameters that limit the results are given, then all information about all classes will be returned. Great power, great responsibility. Deprecated.

URI

class/search

Access Rules

Only admins may use this API.

Input Parameters

  • (r) auth_token = The authentication token. May also be set using the Set-Cookie header.
  • (r) client = A string representing the client.
  • (o) class_urn = A partial class URN limiting the results to only those classes whose URN contains this value.
  • (o) class_name = A partial class name limiting the results to only those classes whose name contains this value.
  • (o) description = A partial class description limiting the results to only those classes whose description contains this value.

Example POST

POST /app/class/search HTTP/1.1
 Host: dev.ohmage.org
 Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
 Content-Length: byte-length-of-content
 Content-Type: application/x-www-form-urlencoded
 
  auth_token=abcfcd36-ab25-4494-8434-7798cb1d718e
  &class_urn=urn:class:los_angeles
  &client=ohmage-MWoC

Output Format

Success

{
    "result" : "success",
    "data" : {
        "urn:class:one" : {
            "name" : "Class One",
            "description" : "This class has a description.",
            "usernames" : [
                "user1",
                "user2",
                "user3"
            ],
            "campaigns" : [
                "urn:campaign:one",
                "urn:campaign:two"
            ],
        },
        "urn:class:two" : {
            "name" : "Class 2",
            "usernames" : [
                "user3",
                "user4",
                "user5"
             ],
             "campaigns" : [
                 "urn:campaign:one"
             ]
        }
    }
}

Failure

See the error page for a description of error codes and their associated descriptions.

Back to Top

Class Update

What does it do?

Allows classes to be modified. Users may be added or removed and the class metadata (name and description) may be modified.

URI

class/update

Access Rules

Admins may perform any update operation on a class. Privileged class users may perform any update on a class to which they belong.

Input Parameters

  • (r) auth_token = The authentication token.
  • (r) client = A string representing the client.
  • (r) class_urn = URN for the class being modified.
  • (o) class_name = A new name for the class.
  • (o) description = A new description of the class.
  • (o) user_role_list_add = A list of users and their roles to add to the class . The format is <username1>;<role1>,<username2>;<role2>,... The users will be added to all of the campaigns associated with this class based on the campaign's default role.
  • (o) user_role_list_remove = A list of users to remove from the class and subsequently prunes their permissions if necessary.

Example POST

POST /app/class/update HTTP/1.1
 Host: dev.ohmage.org
 Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
 Content-Length: byte-length-of-content
 Content-Type: application/x-www-form-urlencoded
 
  auth_token=abcfcd36-ab25-4494-8434-7798cb1d718e
  &client=ohmage-MWoC
  &class_urn=urn:some:class:that:user:is:privileged:in
  &name=New%20name
  &description=Some%20description
  &user_list_add=privileged.gal;privileged,restricted.guy;restricted
  &user_list_remove=user.to.remove1,user.to.remove2

Output Format

Success

{
    "result" : "success"
}

Failure

See the error page for a description of error codes and their associated descriptions.

Back to Top

Class Roster Update

What does it do?

Allows the list of users that belong to a class to be updated. The class rosters are CSV files where each line must be of the form: <Existing class URN>,<Existing username>,<Valid class role>

URI

class/roster/update

Access Rules

Only admins may update class rosters.

Input Parameters

  • (r) auth_token = The authentication token.
  • (r) client = A string representing the client.
  • (r) roster = <Contents of the roster file.>

Example POST

POST /app/class/roster/update HTTP/1.1
 Host: dev.ohmage.org
 Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
 Content-Length: byte-length-of-content
 Content-Type: application/x-www-form-urlencoded
 
  auth_token=abcfcd36-ab25-4494-8434-7798cb1d718e
  &client=ohmage-MWoC
  &roster=<Contents of file.>

Output Format

Success

{
    "result" : "success",
    "warning_messages" : [JSONArray of warning messages]
}

Failure

See the error page for a description of error codes and their associated descriptions.

Back to Top

Class Delete

What does it do?

Removes a class from the system.

URI

class/delete

Access Rules

Only admins may delete classes.

Input Parameters

  • (r) auth_token = The authentication token.
  • (r) client = A string representing the client.
  • (r) class_urn = The URN of the class to remove.

Example POST

POST /app/class/delete HTTP/1.1
 Host: dev.ohmage.org
 Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
 Content-Length: byte-length-of-content
 Content-Type: application/x-www-form-urlencoded
 
  auth_token=abcfcd36-ab25-4494-8434-7798cb1d718e
  &client=ohmage-MWoC
  &class_urn=urn:class:out_of_date

Output Format

Success

{
    "result" : "success"
}

Failure

See the error page for a description of error codes and their associated descriptions.

Back to Top

Clone this wiki locally