What's this

Introduction

Read this section to learn about the Preferences endpoint and its features

One common feature request people have when they use services is the ability to have their preferences synchronized across devices so that they needn't configure two or more devices running the same application. While it's certainly possible to use DropBox, iCloud, or a myriad of other services to make this happen, sometimes it is easier to work with just a single API. This is where the Preferences API can prove useful.

All preferences are application-specific. They cannot be read by other applications nor written to.

Sections

  1. Setting a Preference
  2. Retrieving Preferences
  3. Deleting a Preference

Setting a Preference

Setting a Preference in 10Centuries is really quite simple, as it works as a Key->Store mechanism. Keys can be any string up to 64 multi-byte characters in length, and Values can be any string up to 128 multi-byte characters in length.

From your application, send a request to the following endpoint:

POST https://api.10centuries.org/preferences

Required Data:

key: {any string up to 64 multi-byte characters} value: {any string up to 128 multi-byte characters}

This information can be sent URL-encoded in the POST body or as a JSON package.

Example:

curl -X POST -H "Authorization: {Authorization Token}" \ -H "Content-Type: application/x-www-form-urlencoded" -d "key=puppy_name" -d "value=nozomi 🐶" \ "https://api.10centuries.org/preferences"

If the post was successful, the API will respond with a JSON package:

{ "meta": { "code": 200 }, "data": { "key": "puppy_name", "value": "nozomi 🐶", "updated_at": "2009-02-13 23:31:30", "updated_unix": 1234567890 } }

If posting failed or there was some other problem, the API will respond with an error like the one below:

{ "meta": { "code": 400, "text": "Preference Value Is Too Long. Maximum Length is 128 Characters." }, "data": false }

If the meta.text key is present in this result, it is recommended you show a modal dialog or equivalent containing this message.

Retrieving Preferences

Retrieving Preferences is about as easy as setting it. To retrieve a complete list of Preferences for an application, send a one-line query to the API. This function requires a valid authorization token in the HTTP header.

From your application, send a request to the following endpoint:

GET https://api.10centuries.org/preferences

This information can be sent URL-encoded or as a JSON package.

Example:

curl -X GET -H "Authorization: {Authorization Token}" \ -H "Content-Type: application/x-www-form-urlencoded" \ "https://api.10centuries.org/preferences"

If the post was successful, the API will respond with a JSON package:

{ "meta": { "code": 200 }, "data": [ { "key": "puppy_name", "value": "nozomi 🐶", "updated_at": "2009-02-13 23:31:30", "updated_unix": 1234567890 }, { "key": "baby_name", "value": "Leonard James Akaar", "updated_at": "2009-02-13 23:31:30", "updated_unix": 1234567890 }, { "key": "iguana_name", "value": "Quincey", "updated_at": "2009-02-13 23:31:30", "updated_unix": 1234567890 } ] }

If the request failed or there was some other problem, the API will respond with an error:

{ "meta": { "code": 404, "text": "No Preference Information Found" }, "data": false }

If the meta.text key is present in this result, it is recommended you show a modal dialog or equivalent containing this message.

Deleting a Preference

When a person's preference is no longer required, deleting the record is as easy as sending a single DELETE request with the appropriate key information.

From your application, send a request to the following endpoint:

DELETE https://api.10centuries.org/preferences

Required Data:

key: {any string up to 64 multi-byte characters}

This information can be sent URL-encoded or as a JSON package.

Example:

curl -X DELETE -H "Authorization: {Authorization Token}" \ -H "Content-Type: application/x-www-form-urlencoded" -d "key=iguana_name" \ "https://api.10centuries.org/preferences"

If the request was successful, the API will respond with a JSON package containing the existing preferences:

{ "meta": { "code": 200 }, "data": [ { "key": "puppy_name", "value": "nozomi 🐶", "updated_at": "2009-02-13 23:31:30", "updated_unix": 1234567890 }, { "key": "baby_name", "value": "Leonard James Akaar", "updated_at": "2009-02-13 23:31:30", "updated_unix": 1234567890 } ] }

If request failed or there was some other problem, the API will respond with an error:

{ "meta": { "code": 400, "text": "Could Not Delete Preference" }, "data": false }

If the meta.text key is present in this result, it is recommended you show a modal dialog or equivalent containing this message.