Projects¶
List, Retrieve, Update, Create Project and Project Forms
Where:
pk
- is the project idformid
- is the form idowner
- is the username for the user or organization of the projectinvitation_pk
- is the project invitation id
Register a new Project¶
POST /api/v1/projects
Example¶
{
"url": "https://api.ona.io/api/v1/projects/1",
"owner": "https://api.ona.io/api/v1/users/ona",
"name": "project 1",
"date_created": "2013-07-24T13:37:39Z",
"date_modified": "2013-07-24T13:37:39Z"
}
List of Projects¶
GET /api/v1/projects
Example¶
curl -X GET https://api.ona.io/api/v1/projects
Response¶
[
{
"url": "https://api.ona.io/api/v1/projects/1",
"owner": "https://api.ona.io/api/v1/users/ona",
"name": "project 1",
"date_created": "2013-07-24T13:37:39Z",
"date_modified": "2013-07-24T13:37:39Z"
},
{
"url": "https://api.ona.io/api/v1/projects/4",
"owner": "https://api.ona.io/api/v1/users/ona",
"name": "project 2",
"date_created": "2013-07-24T13:59:10Z",
"date_modified": "2013-07-24T13:59:10Z"
}, ...
]
Get a paginated list of Projects¶
Returns a list of projects using page number and the number of items per page. Use the page
parameter to specify page number and page_size
parameter is used to set the custom page size.
page
- Integer representing the page.page_size
- Integer representing the number of records that should be returned in a single page. The maximum number of items that can be requested in a page via thepage_size
query param is 10,000
GET /api/v1/projects?page
=1
page_size
=2
Example¶
curl -X GET https://api.ona.io/api/v1/projects?page=1&page_size=2
Response¶
[
{
"url": "https://api.ona.io/api/v1/projects/1",
"owner": "https://api.ona.io/api/v1/users/ona",
"name": "project 1",
"date_created": "2013-07-24T13:37:39Z",
"date_modified": "2013-07-24T13:37:39Z"
},
{
"url": "https://api.ona.io/api/v1/projects/4",
"owner": "https://api.ona.io/api/v1/users/ona",
"name": "project 2",
"date_created": "2013-07-24T13:59:10Z",
"date_modified": "2013-07-24T13:59:10Z"
}, ...
]
List of Projects filter by owner/organization¶
GET /api/v1/projects?owner
=owner_username
You can use this to get both members and collaborators of an organization. In the case of organizations, this gives you both members and collaborators under “users”. Under “teams” key we list only the members of the organization.
Example¶
curl -X GET https://api.ona.io/api/v1/projects?owner=ona
Retrieve Project Information¶
GET /api/v1/projects/{pk}
Example¶
curl -X GET https://api.ona.io/api/v1/projects/1
Response¶
{
"url": "https://api.ona.io/api/v1/projects/1",
"owner": "https://api.ona.io/api/v1/users/ona",
"name": "project 1",
"date_created": "2013-07-24T13:37:39Z",
"date_modified": "2013-07-24T13:37:39Z"
}
Update Project Information¶
PUT /api/v1/projects/{pk}
or PATCH /api/v1/projects/{pk}
Example¶
curl -X PATCH -d 'metadata={"description": "Lorem ipsum","location": "Nakuru, Kenya","category": "water"}' https://api.ona.io/api/v1/projects/1
Response¶
{
"url": "https://api.ona.io/api/v1/projects/1",
"owner": "https://api.ona.io/api/v1/users/ona",
"name": "project 1",
"metadata": {
"description": "Lorem ipsum",
"location": "Nakuru, Kenya",
"category": "water"
},
"date_created": "2013-07-24T13:37:39Z",
"date_modified": "2013-07-24T13:37:39Z"
}
Available Permission Roles¶
The following are the available roles in onadata:
member
Default role for user with no permissionreadonly-no-download
Role for a user able to view data but not export itreadonly
Role for a user able to view and download datadataentry-only
Role for a user able to submit data onlydataentry-minor
Role for a user able to submit and view only data he/she submitteddataentry
Role for a user able to submit and view all dataeditor-minor
Role for a user able to view and edit data he/she submittededitor
Role for a user able to view and edit all datamanager
Role for a user with administrative privilegesowner
Role for an owner of a data-set, organization, or project.
Remove a user from a project¶
You can remove a specific user from a project using PUT with payload:
username
of the user you want to removerole
the user has on the projectremove
set remove to True
Example¶
curl -X PUT -d "username=alice" -d "role=readonly" -d "remove=True" http://api.ona.io/api/v1/projects/1/share
Response¶
HTTP 204 NO CONTENT
Assign a form to a project¶
To [re]assign an existing form to a project you need to POST
a payload of formid=FORMID
to the endpoint below.
POST /api/v1/projects/{pk}
/forms
Example¶
curl -X POST -d '{"formid": 28058}' https://api.ona.io/api/v1/projects/1/forms -H "Content-Type: application/json"
Response¶
{
"url": "https://api.ona.io/api/v1/forms/28058",
"formid": 28058,
"uuid": "853196d7d0a74bca9ecfadbf7e2f5c1f",
"id_string": "Birds",
"sms_id_string": "Birds",
"title": "Birds",
"allows_sms": false,
"bamboo_dataset": "",
"description": "",
"downloadable": true,
"encrypted": false,
"owner": "ona",
"public": false,
"public_data": false,
"date_created": "2013-07-25T14:14:22.892Z",
"date_modified": "2013-07-25T14:14:22.892Z"
}
Upload XLSForm to a project¶
POST /api/v1/projects/{pk}
/forms
Example¶
curl -X POST -F xls_file=@/path/to/form.xls https://api.ona.io/api/v1/projects/1/forms
Response¶
{
"url": "https://api.ona.io/api/v1/forms/28058",
"formid": 28058,
"uuid": "853196d7d0a74bca9ecfadbf7e2f5c1f",
"id_string": "Birds",
"sms_id_string": "Birds",
"title": "Birds",
"allows_sms": false,
"bamboo_dataset": "",
"description": "",
"downloadable": true,
"encrypted": false,
"owner": "ona",
"public": false,
"public_data": false,
"date_created": "2013-07-25T14:14:22.892Z",
"date_modified": "2013-07-25T14:14:22.892Z"
}
Get forms for a project¶
GET /api/v1/projects/{pk}
/forms
Example¶
curl -X GET https://api.ona.io/api/v1/projects/1/forms
Response¶
[
{
"url": "https://api.ona.io/api/v1/forms/28058",
"formid": 28058,
"uuid": "853196d7d0a74bca9ecfadbf7e2f5c1f",
"id_string": "Birds",
"sms_id_string": "Birds",
"title": "Birds",
"allows_sms": false,
"bamboo_dataset": "",
"description": "",
"downloadable": true,
"encrypted": false,
"owner": "ona",
"public": false,
"public_data": false,
"date_created": "2013-07-25T14:14:22.892Z",
"date_modified": "2013-07-25T14:14:22.892Z",
"tags": [],
"users": [
{
"role": "owner",
"user": "alice",
...
},
...
]
},
...
]
Get list of projects with specific tag(s)¶
Use the tags
query parameter to filter the list of projects, tags
should be
a comma separated list of tags.
GET /api/v1/projects?tags
=tag1,tag2
List projects tagged smart
or brand new
or both.
Request
^^^^^^^^
curl -X GET https://api.ona.io/api/v1/projects?tag=smart,brand+new
Response¶
HTTP 200 OK
[
{
"url": "https://api.ona.io/api/v1/projects/1",
"owner": "https://api.ona.io/api/v1/users/ona",
"name": "project 1",
"date_created": "2013-07-24T13:37:39Z",
"date_modified": "2013-07-24T13:37:39Z"
},
...
]
Tag a Project¶
A POST
payload of parameter tags
with a comma separated list of tags.
Examples¶
animal fruit denim
- space delimited, no commasanimal, fruit denim
- comma delimited
POST /api/v1/projects/{pk}
/labels
Payload
{"tags": "tag1, tag2"}
Remove a tag from a Project¶
DELETE /api/v1/projects/{pk}
/labels/tag_name
Request¶
curl -X DELETE https://api.ona.io/api/v1/projects/28058/labels/tag1
or to delete the tag “hello world”
curl -X DELETE https://api.ona.io/api/v1/projects/28058/labels/hello%20world
Response¶
HTTP 200 OK
Add a star to a project¶
POST /api/v1/projects/{pk}
/star
Remove a star to a project¶
DELETE /api/v1/projects/{pk}
/star
Get user profiles that have starred a project¶
GET /api/v1/projects/{pk}
/star
Get Project Invitation List¶
GET /api/v1/projects/{pk}/invitations
Example¶
curl -X GET https://api.ona.io/api/v1/projects/1/invitations
Response¶
[
{
"id": 1,
"email":"janedoe@example.com",
"role":"readonly",
"status": 1
},
{
"id": 2,
"email":"johndoe@example.com",
"role":"editor",
"status": 2,
}
]
Get a list of project invitations with a specific status¶
The available choices are:
1
- Pending. Invitations which have not been accepted by recipients.2
- Accepted. Invitations which have been accepted by recipients.3
- Revoked. Invitations which were cancelled.
GET /api/v1/projects/{pk}/invitations?status=2
Example¶
curl -X GET https://api.ona.io/api/v1/projects/1/invitations?status=2
Response¶
[
{
"id": 2,
"email":"johndoe@example.com",
"role":"editor",
"status": 2,
}
]
Create a new project invitation¶
Invite an unregistered user to a project. An email will be sent to the user which has a link for them to create an account.
POST /api/v1/projects/{pk}/invitations
Example¶
curl -X POST -d "email=janedoe@example.com" -d "role=readonly" https://api.ona.io/api/v1/projects/1/invitations
email
: The email address of the unregistered user.
Should be a valid email. If the
PROJECT_INVITATION_EMAIL_DOMAIN_WHITELIST
setting has been enabled, then the email domain has to be in the whitelist for it to be also valid
Example
PROJECT_INVITATION_EMAIL_DOMAIN_WHITELIST=["foo.com", "bar.com"]
Email should not be that of a registered user
role
: The user’s role for the project.
Must be a valid role
Response¶
{
"id": 1,
"email": "janedoe@example.com",
"role": "readonly",
"status": 1,
}
The link embedded in the email will be of the format http://{url}
where:
url
- is the URL the recipient will be redirected to on clicking the link. The default is{domain}/api/v1/profiles
wheredomain
is domain where the API is hosted.
Normally, you would want the email recipient to be redirected to a web app. This can be achieved by
adding the setting PROJECT_INVITATION_URL
Example
PROJECT_INVITATION_URL = {'*': 'https://example.com/register'}
Update a project invitation¶
PUT /api/v1/projects/{pk}/invitations
Example¶
curl -X PUT -d "email=janedoe@example.com" -d "role=editor" -d "invitation_id=1" https://api.ona.io/api/v1/projects/1/invitations/1
Response¶
{
"id": 1,
"email": "janedoe@example.com",
"role": "editor",
"status": 1,
}
Resend a project invitation¶
Resend a project invitation email
POST /api/v1/projects/{pk}/resend-invitation
Example¶
curl -X POST -d "invitation_id=6" https://api.ona.io/api/v1/projects/1/resend-invitation
invitation_id
: The primary key of the ProjectInvitation
to resend.
Must be a
ProjectInvitation
whose status is Pending
Response¶
{
"message": "Success"
}
Revoke a project invitation¶
Cancel a project invitation. A revoked invitation means that project will not be shared with the new user even if they accept the invitation.
POST /api/v1/projects/{pk}/revoke-invitation
Example¶
curl -X POST -d "invitation_id=6" https://api.ona.io/api/v1/projects/1/revoke-invitation
invitation_id
: The primary key of the ProjectInvitation
to resend.
Must be a
ProjectInvitation
whose status is Pending
Response¶
{
"message": "Success"
}
Accept a project invitation¶
Since a project invitation is sent to an unregistered user, acceptance of the invitation is handled when creating a new user.
All pending invitations whose email match the new user’s email will be accepted and projects shared with the user