Skip to content

Class Manipulation

joshuaselsky edited this page Feb 7, 2012 · 16 revisions


What does it do?

Creates classes.

URI

class/create

Accessibility

TODO

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



What does it do?

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

URI

class/read

Accessibility

TODO

Input Parameters

  • (r) auth_token = The authentication token.
  • (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



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

Accessibility

TODO

Input Parameters

  • (r) auth_token = The authentication token.
  • (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



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.

URI

class/search

Accessibility

TODO

Input Parameters

  • (r) auth_token = The authentication token.
  • (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



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

Accessibility

TODO

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_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_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



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

Accessibility

TODO

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



What does it do?

Removes a class from the system.

URI

class/delete

Accessibility

TODO

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