Profiles¶
Register a new User¶
username, email, first_name
Are required fields. username
may
contain alphanumeric, _, @, +, . and - characters
POST /api/v1/profiles
Example¶
{
"username": "demo",
"first_name": "Demo",
"last_name": "User",
"email": "demo@localhost.com",
"city": "Kisumu",
"country": "KE",
...
}
List User Profiles¶
GET /api/v1/profiles
Example¶
curl -X GET https://api.ona.io/api/v1/profiles
To retrieve a specific list of user profiles, an authenicated user should use users
query param whose value
should be a comma-separated list of usernames as seen in the example below. A couple of things to note:
Anonymous users will get an empty result.
Authenticated users without the
users
query param will get their own profiles.
Example¶
curl -X GET https://api.ona.io/api/v1/profiles?users=alice,bob,charlene
Response¶
[
{
"url": "https://api.ona.io/api/v1/profiles/demo",
"username": "demo",
"first_name": "Demo",
"last_name": "User",
"email": "demo@localhost.com",
"city": "",
"country": "",
"organization": "",
"website": "",
"twitter": "",
"gravatar": "https://secure.gravatar.com/avatar/xxxxxx",
"require_auth": false,
"user": "https://api.ona.io/api/v1/users/demo",
"metadata": {},
"joined_on": "2014-11-10T14:22:20.394Z"
},
...
]
Retrieve User Profile Information¶
GET /api/v1/profiles/{username}
GET /api/v1/profiles/{pk}
Example¶
curl -X GET https://api.ona.io/api/v1/profiles/demo
Response¶
{
"url": "https://api.ona.io/api/v1/profiles/demo",
"username": "demo",
"first_name": "Demo",
"last_name": "User",
"email": "demo@localhost.com",
"city": "",
"country": "",
"organization": "",
"website": "",
"twitter": "",
"gravatar": "https://secure.gravatar.com/avatar/xxxxxx",
"require_auth": false,
"user": "https://api.ona.io/api/v1/users/demo",
"metadata": {},
"joined_on": "2014-11-10T14:22:20.394Z"
}
Partial updates of User Profile Information¶
Properties of the UserProfile can be updated using PATCH
http
method. Payload required is for properties that are to be changed in
JSON, for example, {"country": "KE"}
will set the country to KE
.
PATCH /api/v1/profiles/{username}
Example¶
curl -X PATCH -d ‘{"country": "KE"}’ https://api.ona.io/api/v1/profiles/demo -H "Content-Type: application/json"
Response¶
{
"url": "https://api.ona.io/api/v1/profiles/demo",
"username": "demo",
"first_name": "Demo",
"last_name": "User",
"email": "demo@localhost.com",
"city": "",
"country": "KE",
"organization": "",
"website": "",
"twitter": "",
"gravatar": "https://secure.gravatar.com/avatar/xxxxxx",
"require_auth": false,
"user": "https://api.ona.io/api/v1/users/demo",
"metadata": {},
"joined_on": "2014-11-10T14:22:20.394Z"
}
Partial update for email requires password confirmation¶
Example¶
curl -X PATCH -d ‘{"email": "updated@email.com", "password": "password"}’ https://api.ona.io/api/v1/profiles/demo -H "Content-Type: application/json"
Partial update of the metadata profile property¶
This functionality allows for the updating of a key/value object of the
metadata property without overwriting the whole metadata property. For
example, if a user’s metadata was
{"metadata": {"a": "Aaah", "b": "Baah"}}
and we only wanted to
update b
with value Beeh
, we would use this endpoing and add an
overwrite
param with value false
.
PATCH /api/v1/profiles/{username}
Example¶
curl -X PATCH -d ‘{"metadata": {"b": "Beeh"}, "overwrite": "false"}’ https://api.ona.io/api/v1/profiles/demo -H "Content-Type: application/json"
Response¶
{
"url": "https://api.ona.io/api/v1/profiles/demo",
"username": "demo",
"first_name": "Demo",
"last_name": "User",
"email": "demo@localhost.com",
"city": "",
"country": "KE",
"organization": "",
"website": "",
"twitter": "",
"gravatar": "https://secure.gravatar.com/avatar/xxxxxx",
"require_auth": false,
"user": "https://api.ona.io/api/v1/users/demo"
"metadata": {"a": "Aaah", "b": "Beeh"},
"joined_on": "2014-11-10T14:22:20.394Z"
}
Change authenticated user’s password¶
Example¶
curl -X POST -d current_password=password1 -d new_password=password2 https://api.ona.io/api/v1/profile/demouser/change_password
Response¶
{
"username": "demouser",
"access_token": "30557df81ac63729d2865e90f334a5d00fe5e57c",
"temp_token": "0c6a9f167c7074c781f635fe30cb60efa2473317"
}
Get the total number of monthly submissions¶
This gets the total number of submissions made in a month to a specific user’s forms. The result is a count of the submissions to both private and public forms.
If there are no private forms then only the number of submissions to the public forms is returned, and vice versa. If there are no submissions, then an empty dictionary is returned.
Use the month and year as query parameters to get the total number of submissions for a specific month. If no query parameters are used, the result is the number of submissions of the current month. If only month is used, then the year is assumed to be the current year. And if only year is passed, then the month is assumed to be the current year.
Example¶
curl -X GET https://api.ona.io/api/v1/profiles/demouser/monthly_submissions
Response¶
{
"public": 41,
"private": 185
}
Example¶
curl -X GET https://api.ona.io/api/v1/profiles/demouser/monthly_submissions?month=5&year=2018
Response¶
{
"public": 240
}
Email verification¶
By default the email verification functionality is disabled. To enable this feature,
set ENABLE_EMAIL_VERIFICATION
in your settings file to True
. VERIFIED_KEY_TEXT
should also be set to ALREADY_ACTIVATED
. If you have a custom verification url that
you would prefer to be use instead of the default verification url, set it in VERIFICATION_URL
settings variable. The verification url will be appended with the verificaiton key as query
param. Once ENABLE_EMAIL_VERIFICATION
has been set, a verification email will be sent when
a new user is registered using the user profiles endpoint. The email verification endpoint expects
verification_key
query param as well as an optional redirect_url
query param.
verification_key
- A REQUIRED query param which is a hexadecimal associated with a user that expires after 1 day. The expiration day limit can be changed by resetting theACCOUNT_ACTIVATION_DAYS
settings variable.redirect_url
- An OPTIONAL query param that contains the url to redirect to when theverification_key
has successfully been verified
Example¶
curl -X GET https://api.ona.io/api/v1/profiles/verify_email?verification_key=abc&redirect_url=https://red.ir.ect
Successful Response¶
A succesful response or redirect includes 2 values:
username
- the account username of the verified emailis_email_verified
- the status of the verified email. It will beTrue
for a successful response
if there is a redirect url, 2 query params will be appended to the url
<redirect-url>?username=johndoe&is_email_verified=true
If there isn’t a redirect url, the response will be
{
'username': 'johndoe',
'is_email_verified': 'true'
}
Failed Response¶
Missing or invalid verification key
Send verification email¶
To send a verification email, for example when a user has changed his/her email address, the user making the request should
authenticate and provide username
- which should be the same as the user making the request - in the post data. The
requesting user can also provide redirect_url
as part of the post data. The redirect_url
will be appended as query
param to the verification url and used to redirect the user to that url once the verification_key
has successfully been verified.
Example¶
curl -X POST -d username=johndoe -d redirect_url="https://red.ir.ect" https://api.ona.io/api/v1/profiles/send_verification_email
Successful Response¶
Verification email has been sent
Failed Response¶
Verification email has NOT been sent