-
Notifications
You must be signed in to change notification settings - Fork 25
Document Manipulation
Allows users to upload documents (files) to the system.
document/create
Anyone may create a document, but the document must be associated with at least one campaign or class. To associate a document with a campaign or class you must either be an admin or a member of that entity.
- (r) auth_token = A valid authentication token retrieved from user/auth_token.
- (r) client = A short description of the client making the request.
- (r) document_name = The name of the document including the extension, e.g. Todo.rtf.
- (r) privacy_state = The initial privacy state of this document.
- (r) document = The contents of the document.
- (o) description = A description for the document.
Also, one or both of the following must be present. They are each a list of URN-"document role" combination where the URN and role are separated by a semicolon and each pair is separated by a comma, e.g.
first:entity:urn;reader,second:entity:urn;writer.
- document_campaign_role_list = A list of campaigns each associated with a document role.
- document_class_role_list = A list of classes each associated with a document role.
POST /app/document/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=133f5476-5122-11e1-82ed-e4ce8f075a7e
&client=curl
&document_name=Todo.rtf
&privacy_state=shared
&description=Some description
&document_class_urn_list=urn:sys:andwellness;reader
&document=This is the contents of the document
curl -v -F "auth_token=4c042624-747c-4611-8a1a-c666dffb4beb" -F "document_name=testdoc1.txt" -F "document=@/Users/shlurbee/file.txt" -F "privacy_state=private" -F "document_campaign_role_list=urn:campaign:ca:lausd:Addams_HS:CS101:Fall:2011:Advertisement;reader" -F "client=curl" http://localhost:8080/app/document/create
{
"result" : "success",
"document_id" : <The document's identifier>
}
See the error page for a description of error codes and their associated descriptions.
Allows users to view information (metadata) about documents stored in the system. It may be that a user is both directly associated with a document and associated with the same document through a class or campaign. If so and personal_documents is set to false, this API will still return the document and your personal role with the document as well as the campaign's and/or class' role with the document.
document/read
Anyone may read the information about the documents that are directly linked to them. In order to read the information about the documents in a class or campaign, the requesting user must be a member of that entity or an admin.
- (r) auth_token = A valid authentication token retrieved from user/auth_token. May also be set using the Set-Cookie header.
- (r) client = A short description of the client making the request.
- (o) personal_documents = One of "true" or "false". Whether or not the documents that are explicitly associated with the logged-in user should be returned.
- (o) campaign_urn_list = A comma-separated list of campaign identifiers to which the requesting user belongs. The documents associated with these campaigns will be returned.
- (o) class_urn_list = A comma-separated list of class identifiers to which the requesting user belongs. The documents associated with these classes will be returned.
- (o) document_name_search = A whitespace-separated search string that respects double quotes but not single or escaped quotes. It will limit the results to only those whose name contains any of the given tokens.
- (o) document_description_search = A whitespace-separated search string that respects double quotes but not single or escaped quotes. It will limit the results to only those that have a description and whose description contains any of the given tokens.
- (o) start_date = The returned documents (last modified date) should be no earlier than the start_date. The expected date format is either YYYY-MM-DD or YYYY-MM-DD HH:MM:SS.
- (o) end_date = The returned documents (last modified date) should be no later than the end_date.
Note: 'personal_documents' is no longer required. This a change that supports backwards compatibility while allowing for new functionality. Now, supplying 'personal_documents' and/or 'campaign_urn_list' and/or 'class_urn_list' will limit the list of documents to only those that match the criteria, but supplying none of those parameters will initialize the list with all documents visible to the requesting user.
POST /app/document/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
&personal_documents=false
&class_urn_list=urn:class:ptsd:beta
&client=ohmage-gwt
curl -v -d "auth_token=808e5e75-7720-41e5-b418-50c21117eaeb&personal_documents=true&client=curl" http://localhost:8080/app/document/read
{
"result" : "success",
"data" : {
"<document ID>" : {
"name" : "<document name>",
"description" : "<document description or an empty string if there isn't one>",
"privacy_state" : "<document privacy state>",
"size" : <the document's size>,
"last_modified" : "<YYYY-DD-MM hh:mm:ss format for the last time the document was modified>",
"user_max_role" : "<The maximum role for the requesting user for this document. This is simply the maximum of all of the following roles, which can be increased to "writer" if only a "reader" but are privileged in any class to which this document is associated or a supervisor in any campaign to which this document is associated.>"
"user_role" : "<the direct document role for the requesting user should one exist or an empty string if not>",
"campaign_role" : {
"<campaign identiifer>" : "<the document role for this campaign>",
...
}
"class_role" : {
"<class identifier>" : "<the document role for this class>",
...
}
}
}
}
See the error page for a description of error codes and their associated descriptions.
Allows users to retrieve the contents of documents stored in the system.
document/read/contents
The requesting user must be associated with the document in some capacity, either directly linked to the user or directly linked to a class or campaign to which the user is a member. Or, the requesting user needs to be an admin.
- (r) auth_token = A valid authentication token retrieved from user/auth_token. May also be set using the Set-Cookie header.
- (r) client = A short description of the client making the request.
- (r) document_id = An id of a document in the system.
POST /app/document/contents/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
&client=ptsdexplorer
&document_id=the-document's-unique-identifier
curl -v -d "auth_token=808e5e75-7720-41e5-b418-50c21117eaeb&document_id=a08e5e75-7720-41e5-b418-50c21117eaeb&client=curl" http://localhost:8080/app/document/read/contents
The requested document is returned in the HTTP stream
See the error page for a description of error codes and their associated descriptions.
Allows users to retrieve the contents of documents stored in the system.
document/update
The user must satisfy the following schema:
- Be an admin.
Or
- Satisfy one of the following:
- Have the "owner" document role either directly or through a campaign or class to which they belong.
- Have the "writer" document role either directly or through a campaign or class to which they belong.
- Be a supervisor in any campaign to which the document is associated.
- Be privileged in any class to which the document is associated.
- Be a member of all of the campaigns with which they are trying to associate the document.
- Be a member of all of the classes with which they are trying to associate the document.
- Not giving a user, campaign, or class a higher role than they have.
- Not disassociating the document from any campaign that has a higher role than they have.
- Not disassociating the document from any class that has a higher role than they have.
- (r) auth_token = A valid authentication token retrieved from user/auth_token.
- (r) client = A short description of the client making the request.
- (r) document_id = An id of a document in the system.
- (o) document_name = The new name of the document including the extension, e.g. Todo.rtf.
- (o) privacy_state = The new privacy state of this document.
- (o) document = The new contents of the document.
- (o) description = A description for the document.
- (o) campaign_role_list_add = A comma-separated list of campaign-role pairs. The document should be associated with each campaign and its given document role.
- (o) campaign_list_remove = A comma-separated list of campaign IDs with which the document should no longer be associated.
- (o) class_role_list_add = A comma-separated list of class-role pairs. The document should be associated with each class and its given document role.
- (o) class_list_remove = A comma-separated list of class IDs with which the document should no longer be associated.
- (o) user_role_list_add = A comma-separated list of user-role pairs. The document should be directly associated with each user and its given document role.
- (o) user_list_remove = A comma-separated list of usernames with which the document should no longer be associated.
- To update an entity from one document role to another, simply add their <identifier>-<new role> pair to the appropriate <entity>_role_list_add list. It is acceptable if they already have the given role.
- The deletion update is done before the addition update, so if you place a user in both the <entity>_list_remove and <entity>_role_list_add lists, the user will be disassociated with the document and then re-associated with the document. Currently, there is no difference between doing this and doing the above, but the former is preferred in the event that we decide to take certain steps when an entity is disassociated with a document or if there are no longer any associations with the document which may happen between the disassociation and association.
POST /app/document/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=ptsdexplorer
&document_id=the-document's-unique-identifier
&document_name=Todo.rtf
&privacy_state=shared
&description=Some description
&document=This is the new contents of the document
&user_role_list_add=new.guy;reader,cool.guy;owner
&user_list_remove=old.guy
curl -v -d "auth_token=808e5e75-7720-41e5-b418-50c21117eaeb&document_id=a08e5e75-7720-41e5-b418-50c21117eaeb&client=curl" http://localhost:8080/app/document/update
{
"result": "success"
}
See the error page for a description of error codes and their associated descriptions.
Allows users to delete documents stored in the system.
document/delete
The user must be an admin, an owner either directly or though a campaign or class to which the document belongs, a supervisor in any of the campaigns to which the document belongs, or privileged in any of the classes to which the document belongs.
- (r) auth_token = A valid authentication token retrieved from user/auth_token.
- (r) client = A short description of the client making the request.
- (r) document_id = An id of a document in the system.
POST /app/document/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=ptsdexplorer
&document_id=the-document's-unique-identifier
curl -v -d "auth_token=808e5e75-7720-41e5-b418-50c21117eaeb&document_id=a08e5e75-7720-41e5-b418-50c21117eaeb&client=curl" http://localhost:8080/app/document/delete
{
"result": "success"
}
See the error page for a description of error codes and their associated descriptions.