Simperium HTTP


Authentication

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.

https://auth.simperium.com
X-Simperium-API-Key: {api_key from dashboard}

https://api.simperium.com
X-Simperium-Token: {access_token from authorizing a user}

URL format

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.


create

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


authorize

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


update

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)


reset_password

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


delete

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


Data API Overview

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.


index

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) }
 }, {...}]

Retrieving an object

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 }


Modifying or creating an object

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

Example

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"}

Deleting an object

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


Sharing an object

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_accesstrue/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


All bucket changes

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


List buckets

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