sync
Description
(Offline capable) clients use this method to sync their things with the server.
HTTP Method
GET or POSTExplorer
Try in the explorerParameters
| Name | Request-Type | Type | Required | Description |
|---|---|---|---|---|
| from | GET or POST | number | no | use a previous returned pos value. Output will then only contained the changes since the last position. Leaving it out or setting it to 0 will transmit all things. |
| skip | GET or POST | number | no | this will skip the first x things from the sync. The thingCount return value is unaffected. |
| limit | GET or POST | number | no | this will limit the number of things returned. Use skip and limit to get the next batch. The thingCount return value is unaffected. |
| new_thing | POST | JSON object | no | denotes a thing that is to be created (or has been created by a client, for example while being offline). |
| In its response the server will tell the client for each local_id what _id has been assigned. see note below for submitting multiple things. format of a new_thing, see below. | ||||
| changed_thing | POST | JSON object | no | denotes a thing that is to be changed (or was changed on the client). |
| see note below for submitting multiple things. format of a thing, see below. | ||||
| deleted_thing | POST | _id | no | specifies a thing to be deleted (or that was deleted on the client). |
| see note below for submitting multiple things. format of a deleted thing, see below. | ||||
| tag[tagname] | POST | JSON object | no | specifies a tag to be changed. see below |
| skip_id | POST | _id | no | you can omit ids from the changed or deleted things by using this parameter. |
Note: If you want to submit multiple things, you can just wrap them in a json array [{"title":"..."}, ...]. If for some reason you prefer to send them separately (for example, beause there are too many), use multiple *_thing[] parameters: for example changed_thing[]=...&changed_thing[]=...
new_thing format
{
"local_id": "an arbitrary id that the client uses to identify this thing which does not yet exist on the server",
"title": "title of the thing",
"tags": "space separated tags of the thing",
"date": "unixtime when the thing was created",
"url": "url of the thing, only needs to specified when set",
"html": "the html resp. note of the thing, only needs to specified when set",
"archived": "true or false, if missing false is assumed",
"todoStatus": "true or false, only if thing is a todo (through a special tag)"
}
The local_id could be an auto increment id from the client's database. When specifying multiple things they cannot have the same local_id.
changed_thing format
{
"_id": "alphanumeric id of the thing that has been given by the server earlier",
"title": "title of the thing",
"tags": "space separated tags of the thing",
"date": "unixtime when the thing was created",
"url": "url of the thing, only needs to specified when set",
"html": "the html resp. note of the thing, only needs to specified when set",
"archived": "true or false, if missing false is assumed",
"todoStatus": "true or false, only if thing is a todo (through a special tag)"
}
deleted_thing format
"server_id_of_deleted_thing"
tag[tagname] format
The URL parameter for the tag thinkery would therefore be tag[thinkery].
{
"favorite": "true or false",
"color": "false or the hex code of a background color",
"todo": "true or false"
}
Returns
{
"pos": "the current position. remember and use later with 'from' (see above)",
"thingCount": "the number of things that will be listed as new, changed or deleted below (omitted when 0)",
"tags": {
"tagname": {
"favorite": "true or false",
"color": "false or the hex code of a background color",
"todo": "false, 'strike' or 'dont-strike', if not false then things with that tag should have a checkbox"
}
},
"things": {
"new": {
"local_id as specified from the client": "assigned _id on the server"
},
"changed": [
{
"_id": "alphanumeric id of the thing",
"title": "title of the thing",
"tags": "space separated tags of the thing",
"date": "unixtime when the thing was created",
"url": "url of the thing, only included if it is set",
"html": "the html resp. note of the thing, only included if it is set",
"archived": "true, only set when it is an archived thing",
"todoStatus": "true or false, only if thing is a todo (through a special tag)"
}
],
"deleted": [
"_id of a thing that has been deleted"
]
}
}
Remarks
- returned.things.new is only specified when one or more new_thing[] was specified. The client must set this new id specified by the server as the _id for the thing to which it is refered to henceforth.
- If a new thing was created through the web interface or another client, it will be returned under returned.things.changed. So if a thing is included with an _id that is new to the client, this thing should be created on the client. Otherwise the client will use the _id field to update the thing on the client.
- If from is left out or specified as 0, then the tags section will include all favorite tags and all special tags (as specified by the user in the settings).
Examples
Consider a user with only 1 thing in his thinkery.
GET /v1/sync?from=0 HTTP/1.1 Host: api.thinkery.me Authorization: access-token=the-token-you-received { "pos": 1, "thingCount": 1, "things": { "changed": [ { "_id": "arbitrary-id-on-the-server-1", "title": "my first thing", "date": 1714320674, "tags": "test todo" } ] } }
User creates a new thing on the client, in its database this new thing could now look like this:
| id | server_id | title | tags | created | locally_changed |
|---|---|---|---|---|---|
| 2 | NULL | interesting thought | thought | 1714320689 | true |
Now that the client is back online, it reports it to the server:
POST /v1/sync HTTP/1.1 Host: api.thinkery.me Authorization: access-token=the-token-you-received Content-Type: application/x-www-form-urlencoded Content-Length: 135 from=1&new_thing[]={"local_id":2,"title":"interesting thought","tags":"thought","date":1714320689} (this would be urlencoded) { "pos": 2, "things": { "new": { "2": "arbitrary-id-on-the-server-2" } } }
In client database the thing would now look like this:
| id | server_id | title | tags | created | locally_changed |
|---|---|---|---|---|---|
| 2 | arbitrary-id-on-the-server-2 | interesting thought | thought | 1714320689 | false |
Now another client would ask:
GET /v1/sync?from=1 HTTP/1.1 Host: api.thinkery.me Authorization: access-token=the-token-you-received { "pos": 2, "thingCount": 1, "things": { "changed": [ { "_id": "arbitrary-id-on-the-server-2", "title": "interesting thought", "tags": "thought", "date": 1714320689 } ] } }
Or a fresh client would ask:
GET /v1/sync?from=0 HTTP/1.1 Host: api.thinkery.me Authorization: access-token=the-token-you-received { "pos": 2, "thingCount": 2, "things": { "changed": [ { "_id": "arbitrary-id-on-the-server-1", "title": "my first thing", "date": 1714320674, "tags": "test todo" }, { "_id": "arbitrary-id-on-the-server-2", "title": "interesting thought", "tags": "thought", "date": 1714320689 } ] } }
Consider a user with only 1 thing in his thinkery.
GET /v1/sync?from=0 HTTP/1.1 Host: api.thinkery.me Authorization: access-token=the-token-you-received { "pos": 1, "thingCount": 1, "things": { "changed": [ { "_id": "arbitrary-id-on-the-server-1", "title": "my first thing", "date": 1714320674, "tags": "test todo" } ] } }
User makes the tag todo a favorite tag in the web interface.
The client might be notified via push notification that something is new (see register/device and asks the server.
GET /v1/sync?from=1 HTTP/1.1 Host: api.thinkery.me Authorization: access-token=the-token-you-received { "pos": 2, "tags": { "todo": { "favorite": true, "color": false, "todo": false } } }
On the other hand, a new client would receive:
GET /v1/sync?from=0 HTTP/1.1 Host: api.thinkery.me Authorization: access-token=the-token-you-received { "pos": 2, "thingCount": 1, "tags": { "todo": { "favorite": true, "color": false, "todo": false } }, "things": { "changed": [ { "_id": "arbitrary-id-on-the-server-1", "title": "my first thing", "date": 1714320674, "tags": "test todo" } ] } }