Skip to content

Annotation Manipulation

Jump to bottom
joshuaselsky edited this page Feb 4, 2012 · 28 revisions

Annotation Create

What does it do?

Allows users to annotate different entities in the system: survey responses, prompt responses, annotations, and dates. On successful annotation creation, an id (a UUID) is returned.

URL

annotation/create

Accessibility

Campaign supervisors may create annotations for all participants in their campaigns.

Input Parameters

  • (r) auth_token = authentication token.
  • (r) client = the ubiquitous client parameter
  • (r) item = survey_response | prompt_response | annotation | date
  • (r) username = the username of the user who owns the item being annotated
  • (r) id = the UUID of the survey_response being annotated | the UUID of the prompt_response being annotated
  • (r) time = epoch milliseconds since the UNIX epoch
  • (r) timezone = the timezone the client application is running in
  • (r) annotation = a JSON object with arbitrary key-value pairs
  • (o) campaign_urn = required for date annotation, disallowed for all other item types
  • (o) prompt_id = required for prompt_response annotation where the value must be the prompt id of the prompt response; disallowed for all other item types
  • (o) repeatable_set_id = used for the prompt_response annotation: the repeatable set id of the prompt_response, if one exists
  • (o) repeatable_set_iteration = used for the prompt_response annotation: the repeatable set iteration of the prompt_response, if one exists

Example survey_response annotation POST

POST /app/annotation/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=02c59bf6-65a2-478e-bcb4-675b543ace26
 &client=omh.dvu
 &username=madonna
 &item=survey_response
 &id=a299df12-24c6-4e79-bb09-2563b62d1df0
 &annotation={"text":"get into the groove"}
 &time=1328312397
 &timezone=GMT

Example prompt_response annotation POST

POST /app/annotation/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=02c59bf6-65a2-478e-bcb4-675b543ace26
 &client=omh.dvu
 &username=madonna
 &item=prompt_response
 &id=a299df12-24c6-4e79-bb09-2563b62d1df0
 &prompt_id=lyrics
 &annotation={"text":"if we took a holiday"}
 &time=1328312397
 &timezone=GMT

Example annotation annotation POST

POST /app/annotation/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=02c59bf6-65a2-478e-bcb4-675b543ace26
 &client=omh.dvu
 &username=madonna
 &item=annotation
 &id=aa4805a2-4ec0-11e1-900f-e4ce8f075a7e
 &annotation={"text":"it would be so nice"}
 &time=1328312397
 &timezone=GMT

Example date annotation POST

POST /app/annotation/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=02c59bf6-65a2-478e-bcb4-675b543ace26
 &client=omh.dvu
 &username=madonna
 &campaign_urn=urn:campaign:pop_singers
 &item=date
 &id=aa4805a2-4ec0-11e1-900f-e4ce8f075a7e
 &annotation={"text":"We've only got 4 minutes to save the world."}
 &time=1328312397
 &timezone=GMT

Output Format

Success

{
   "result" : "success",
   "id" : "89a206c6-4ec1-11e1-a26e-e4ce8f075a7e"
}

Failure

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

Annotation Read

What does it do?

Allows users to read different annotations in the system.

URL

annotation/read

Accessibility

Campaign supervisors may read annotations for all participants in their campaigns. Participants may read annotations that have been assigned to the annotated items they own.

Input Parameters

  • (r) auth_token = authentication token.
  • (r) client = the ubiquitous client parameter
  • (r) item = survey_response | prompt_response | annotation | date
  • (r) username = the username of the user who owns the item being annotated
  • (r) id = the UUID of the survey_response being annotated | the UUID of the prompt_response being annotated
  • (r) time = epoch milliseconds since the UNIX epoch
  • (r) timezone = the timezone the client application is running in
  • (r) annotation = a JSON object with arbitrary key-value pairs
  • (o) campaign_urn = required for date annotation, disallowed for all other item types
  • (o) prompt_id = required for prompt_response annotation where the value must be the prompt id of the prompt response; disallowed for all other item types
  • (o) repeatable_set_id = used for the prompt_response annotation: the repeatable set id of the prompt_response, if one exists
  • (o) repeatable_set_iteration = used for the prompt_response annotation: the repeatable set iteration of the prompt_response, if one exists

Example survey_response annotation POST

POST /app/annotation/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=02c59bf6-65a2-478e-bcb4-675b543ace26
 &client=omh.dvu
 &username=madonna
 &item=survey_response
 &id=a299df12-24c6-4e79-bb09-2563b62d1df0
 &annotation={"text":"get into the groove"}
 &time=1328312397
 &timezone=GMT

Example prompt_response annotation POST

POST /app/annotation/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=02c59bf6-65a2-478e-bcb4-675b543ace26
 &client=omh.dvu
 &username=madonna
 &item=prompt_response
 &id=a299df12-24c6-4e79-bb09-2563b62d1df0
 &prompt_id=lyrics
 &annotation={"text":"if we took a holiday"}
 &time=1328312397
 &timezone=GMT

Example annotation annotation POST

POST /app/annotation/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=02c59bf6-65a2-478e-bcb4-675b543ace26
 &client=omh.dvu
 &username=madonna
 &item=annotation
 &id=aa4805a2-4ec0-11e1-900f-e4ce8f075a7e
 &annotation={"text":"it would be so nice"}
 &time=1328312397
 &timezone=GMT

Example date annotation POST

POST /app/annotation/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=02c59bf6-65a2-478e-bcb4-675b543ace26
 &client=omh.dvu
 &username=madonna
 &campaign_urn=urn:campaign:pop_singers
 &item=date
 &id=aa4805a2-4ec0-11e1-900f-e4ce8f075a7e
 &annotation={"text":"We've only got 4 minutes to save the world."}
 &time=1328312397
 &timezone=GMT

Output Format

Success

{
   "result" : "success",
   "id" : "89a206c6-4ec1-11e1-a26e-e4ce8f075a7e"
}

Failure

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

Clone this wiki locally