There are two main endpoints for Simperium, auth.simperium.com and api.simperium.com. Both require SSL and need different authentication headers. auth.simperium.com endpoints manages users, creating them, deleting them, and signing them in and requires a valid API key. API keys can be managed from your application dashboard. api.simperium.com is used to access any data stored in Simperium and requires a valid access token. Tokens currently must be generated by signing in a user.
X-Simperium-API-Key: {api_key from dashboard}
X-Simperium-Token: {access_token from authorizing a user}
The application id and API version must be sent in the URL:
https://{auth|api}.simperium.com/{api_version}/{app_id}/...
Currently the API version must be set to 1, and you can find your application id on the dashboard.
All data is versioned in Simperium. Every update to an object is recorded as a change object and the resulting object state is stored as an object version.
You may be able to retrieve old versions of a specific entity, or simply query the document associated to the latest revision.
POST https://auth.simperium.com/1/{ app_id }/create/
Creates a user if they don't already exist.
>>> curl -H 'X-Simperium-API-Key: { api_key }' \
-d '{"username":"test@test.com", "password":"test"}' \
https://auth.simperium.com/1/{ app_id }/create/
>>> {"username": "test@test.com", "access_token": "84f27d20f93b414f8b7bc3441f87c9e1", "userid": "f5067cc81c9c26dcdca468f0cdf60508"}
username — Usernames currently must be a valid email address
password — Password for the user
Returns:
access_token — Use token to access data for this user
userid — A unique id that won't change if user changes their username
POST https://auth.simperium.com/1/{ app_id }/authorize/
Gets a new access token for a user.
>>> curl -H 'X-Simperium-API-Key: { api_key }' \
-d '{"username":"test@test.com", "password":"test"}' \
https://auth.simperium.com/1/{ app_id }/authorize/
>>> {"username": "test@test.com", "access_token": "84f27d20f93b414f8b7bc3441f87c9e1", "userid": "f5067cc81c9c26dcdca468f0cdf60508"}
username — Usernames currently must be a valid email address
password — Password for the user
Returns:
access_token — Use token to access data for this user
userid — A unique id that won't change if user changes their username
POST https://auth.simperium.com/1/{ app_id }/update/
Updates username or password for a user. Requires both current username and password.
>>> curl -H 'X-Simperium-API-Key: { api_key }' \
-d '{"username":"test@test.com", "password":"test", "new_username":"test2@test.com"}' \
https://auth.simperium.com/1/{ app_id }/update/
>>> {"status": "success"}
username — Usernames currently must be a valid email address
password — Password for the user
new_username — New username (optional)
new_password — New password (optional)
POST https://auth.simperium.com/1/{ app_id }/reset_password/
Change password for a user without current password. Requires an API key with admin privileges.
>>> curl -H 'X-Simperium-API-Key: { api_key with admin privileges }' \
-d '{"username":"test@test.com", "new_password":"newpass"}' \
https://auth.simperium.com/1/{ app_id }/reset_password/
>>> {"status": "success"}
username — Usernames currently must be a valid email address
new_password — New password
POST https://auth.simperium.com/1/{ app_id }/delete/
Deletes a user and all user data. Requires an API key with admin privileges.
>>> curl -H 'X-Simperium-API-Key: { api_key with admin privileges }' \
-d '{"username":"test@test.com"}' \
https://auth.simperium.com/1/{ app_id }/delete/
>>> {"status": "success"}
username — Usernames currently must be a valid email address
GET https://api.simperium.com/1/{ app_id }/{ bucket_name }/index
Retrieves a page of objects for a bucket
>>> curl -H 'X-Simperium-Token: { access_token }' \
https://api.simperium.com/1/{ app_id }/{ bucket_name }/index
>>> {
"index": [
{ "id": "item1",
"v": 1 },
{ "id": "item2",
"v": 3 },
],
"current": "4f987082d240991a7e0200f6"
}
Query parameters:
limit — Maximum number of objects to return (int)
mark — A cursor to continue retrieving pages from (returned from previous index fetch) (string)
since — Return only objects changed since this cursor (string)
data — Include current object data (bool)
Returns:
current — A cursor referencing the latest change for this user in this bucket
mark — If returned, a cursor indicating next page to fetch index for
index — A list of objects
[{ "id" : "{ object id }",
"v" : { object version },
"d" : { object data (data=True) }
}, {...}]
GET https://api.simperium.com/1/{ app_id }/{ bucket_name }/all
An endpoint to retrieve all changes to objects in the bucket for any user. Supports long-polling. By default this will return up to 99 change objects. Typical usage would be to call this in a loop, passing in the cv of the last change received to process all changes.
>>> curl -H 'X-Simperium-Token: { access_token }' \
https://api.simperium.com/1/{ app_id }/{ bucket_name }/all
>>> [ {
"ccid": "{ client change id }",
"clientid": "{ client id }",
"cv": "{ cursor for change }",
"id" : "{ object id }",
"username" : "{ username (if username is set)}",
"d" : { object data (if data is set)}
}, { ... } ]
X-Simperium-Token — Authentication token must have been created using an API key that has admin privileges
Query parameters:
cv — A cursor id to retrieve changes from
data — Send 1 or True to return the current data with each change for an object
username — Set this parameter to 1 to return the username with each change
Returns:
An array of change objects
GET https://api.simperium.com/1/{ app_id }/buckets
Gets a list of all buckets for this app.
>>> curl -H 'X-Simperium-Token: { access_token }' \
https://api.simperium.com/1/{ app_id }/buckets
>>> { "buckets" :
[
{ "name" : "yourbucket" },
{ "name" : "yourotherbucket" }
]
}
X-Simperium-Token — Authentication token must have been created using an API key that has admin privileges
Returns:
An array of bucket objects
DELETE https://api.simperium.com/1/{ app_id }/{ bucket_name }
Deletes a bucket and all of its contents.
>>> curl -H 'X-Simperium-Token: { access_token }' -X DELETE \
https://api.simperium.com/1/{ app_id }/{ bucket_name }
X-Simperium-Token — Authentication token must have been created using an API key that has admin privileges
Returns:
no data - HTTP response code 200 indicates success
GET https://api.simperium.com/1/{ app_id }/{ bucket_name }/i/{ object id }[/v/{ version }]
Retrieves object data from the bucket
>>> curl -H 'X-Simperium-Token: { access_token }' \
https://api.simperium.com/1/{ app_id }/{ bucket_name }/i/{ object id }
>>> { "sample": "object" }
URL parameters:
/v/{version number} — A specific object version to retrieve
Returns:
X-Simperium-Version — An HTTP response header indicating the object version retrieved
{ data }
POST https://api.simperium.com/1/{ app_id }/{ bucket_name }/i/{ object id }[/v/{ version }]
Modify object data in the bucket or create an object. If no version is specified, the latest version of the object (if it exists) is updated.
>>> curl -H 'X-Simperium-Token: { access_token }' \
https://api.simperium.com/1/{ app_id }/{ bucket_name }/i/{ object id } -d '{"your" : "newdata"}'
URL parameters:
/v/{version number} — A specific object version to modify
Query parameters:
clientid — A unique string identifying your client (useful for debugging and tracking changes)
ccid — A unique id for this change. If you need to resubmit this operation, you should send the same ccid to prevent duplicate operations.
response — Set this parameter to 1 to return resulting data
replace — By default, this endpoint will update the object with the data you submit. If you omit fields, then they won't be changed. If you need to remove fields, set replace to 1 to completely replace the object data with what you submit.
Returns:
X-Simperium-Version — An HTTP response header indicating the current object version after the modify
{ data } — If response was set to 1 in query parameter
Response codes
200 — success
400 — bad request, check input data
401 — authorization error, check token
404 — specified object version does not exist
412 — empty change, object was not modified
This request creates an object, if the object already exists, this would be equivalent to updating the "a" field on the object 'newitem' to "b".
>>> curl -H 'X-Simperium-Token: access_token' \
-d '{"a": "b"}'
https://api.simperium.com/1/your-app-id/sample/i/newitem?response=1
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 10
X-Simperium-Version: 1
{"a": "b"}
A second request to create the exact same object fails because no data has changed. We get error 412.
>>> curl -H 'X-Simperium-Token: access_token' \
-d '{"a": "b"}'
https://api.simperium.com/1/your-app-id/sample/i/newitem?response=1
HTTP/1.1 412 Precondition Failed
Content-Length: 0
X-Simperium-Version: 1
We then modify the object created above. We update the "a" field to add a character 'c', so the value of "a" should be "bc". We specify that we are modifying version 1. The call returns as expected, the data has been modified and the version number has been increased.
>>> curl -H 'X-Simperium-Token: access_token' \
-d '{"a": "bc"}'
https://api.simperium.com/1/your-app-id/sample/i/newitem/v/1?response=1
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 11
X-Simperium-Version: 2
{"a": "bc"}
To simulate what would happen if a different client also wanted to modify the same object, we make another request, also modifying version 1. This time we are adding a different character, 'd', so our request is to update version 1 so that field "a" is "bd". The server takes the request, and transforms it because currently, by default, strings have automatic conflict resolution. The resulting data is that field "a" contains "bcd", incorporating changes from both requests that were trying to modify the same version of the same object.
>>> curl -H 'X-Simperium-Token: access_token' \
-d '{"a": "bd"}'
https://api.simperium.com/1/your-app-id/sample/i/newitem/v/1?response=1
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 12
X-Simperium-Version: 3
{"a": "bcd"}
DELETE https://api.simperium.com/1/{ app_id }/{ bucket_name }/i/{ object id }[/v/{ version }]
Deletes object from the bucket.
>>> curl -H 'X-Simperium-Token: { access_token }' -X DELETE \
https://api.simperium.com/1/{ app_id }/{ bucket_name }/i/{ object id }
URL parameters:
/v/{version number} — A specific object version to delete, if you suppply this, delete will only succeed if the current object version matches this parameter
Query parameters:
clientid — A unique string identifying your client (useful for debugging and tracking changes)
ccid — A unique id for this change. If you need to resubmit this operation, you should send the same ccid to prevent duplicate operations.
Returns:
X-Simperium-Version — An HTTP response header indicating the current object version after the modify
no data
POST https://api.simperium.com/1/{ app_id }/{ bucket_name }/i/{ object id }/share/{ username }
Shares an object with another user (target user). The object will appear in the other user's bucket with the object's id prefixed with the original user's userid.
>>> curl -H 'X-Simperium-Token: { access_token }' \
https://api.simperium.com/1/{ app_id }/{ bucket_name }/i/{ object id }/share/{ target username } -d '{"write_access": true}'
Request body: (as JSON object)
write_access — true/false, whether or not the target user can modify this object
URL parameters:
{ username } — The Simperium username (created through create) to share this object with
Query parameters:
clientid — A unique string identifying your client (useful for debugging and tracking changes)
ccid — A unique id for this change. If you need to resubmit this operation, you should send the same ccid to prevent duplicate operations.
Returns:
no data - HTTP response code 200 indicates success