Response Logic
The application is pretty much self aware of the response type to send you based on the request. There is no need to call a different url for the API vs. web view vs. internal XMLHttpRequest call. They are all the same.
We are going to use the example of getting your most current marks, 30 at a time (system default). We will do this for the web view, the API call and an internal XMLHttpRequest call. External XMLHttpRequest calls (JSONP) are treated like API calls. You should avoid this as it will expose your security token.
Simply log into your site and send a request via your browser to http://SITENAME.com/marks. You will be returned a response like the following.
Array
(
[labels] => Array
(
[0] => stdClass Object
(
[label_id] => 1
[name] => Unlabeled
[slug] => unlabeled
[active] => 1
[type] => label
[total_marks] => 35
)...
)
[marks] => Array
(
[0] => stdClass Object
(
[mark_id] => MARK_ID
[notes] => NOTES
[created_on] => 0000-00-00 00:00:00
[archived_on] =>
[title] => TITLE
[url] => URL
[embed] => EMBED
[label_id] => 1
[label_name] => Unlabeled
[tags] => Array
(
)
)
[page] => 1
[pages] => 3
[per_page] => 30
[stats] => Array
(
[saved] => Array
(
[today] => 0
[yesterday] => 0
[2 days ago] => 0
[3 days ago] => 0
[4 days ago] => 0
)
[archived] => Array
(
[today] => 0
[yesterday] => 0
[2 days ago] => 0
[3 days ago] => 0
[4 days ago] => 0
)
[marks] => Array
(
[today] => 0
[yesterday] => 0
[last week] => 0
[last_month] => 11
[last 3 months] => 11
[last 6 months] => 11
[last year] => 16
[ages ago] => 71
)
)
[tags] => Array
(
[popular] => Array
(
[0] => stdClass Object
(
[tag_id] => 3
[total] => 2
[name] => My Tag
[slug] => my-tag
)
[1] => stdClass Object
(
[tag_id] => 1
[total] => 1
[name] => Tag 2
[slug] => tag-2
)
)
[recent] => Array
(
[0] => stdClass Object
(
[tag_id] => 1
[total] => 1
[name] => Tag 2
[slug] => tag-2
)
[1] => stdClass Object
(
[tag_id] => 3
[total] => 2
[name] => My Tag
[slug] => my-tag
)
)
)
[total] => 72
[view] => marks/indexThe web view returns a bit more data than just the marks. It will also return some stats, your most popular tags, your most recently used tags and system level labels. When you call this same url using an XMLHttpRequest or API call you just get the marks data and totals information.
The system knows it's an internal XMLHttpRequest call by looking at the server headers. It sees that an XMLHttpRequest request was sent and the hosts are the same. It says 'Hey this is us!'. If your request matches this criteria the system won't look for your security token; it will use your current session information for the user.
Simply send an XMLHttpRequest request to /marks. The response will be below.
{
"marks":{
"0":{
"mark_id":"MARK ID",
"notes":"NOTE",
"created_on":"0000-00-00 00:00:00",
"archived_on":null,
"title":"TITLE",
"url":"URL",
"embed":null,
"label_id":"1",
"label_name":"Unlabeled",
"tags":{
}
}
},
"page":1,
"pages":3,
"per_page":30,
"total":72
}As you can see you still get the same marks information, it's just in a different format. We don't include any of the stats and such here by default since you are just polling for marks info. You can get the stats, tags, etc all on different URL calls. All accesible from anywhere at anytime.
Generally to make an API call you are going to use a utility like cURL to hit access a URL remotely. Magically you still use the same access point as above. The only change is you must send your user_token provided to you with your account. API calls don't start a session, we read your random 30 digit security token and look up your user information. Anytime user_token is found in the URL we treat this as API call. You cannot update any of your user information with the API, only access your marks and labels.
Simply send an API request to https://SITE.com/marks?user_token={TOKEN}. It is recommended to always use a secure connection. The response will be below.
{
"marks":{
"0":{
"mark_id":"MARK ID",
"notes":"NOTE",
"created_on":"0000-00-00 00:00:00",
"archived_on":null,
"title":"TITLE",
"url":"URL",
"embed":null,
"label_id":"1",
"label_name":"Unlabeled",
"tags":{
}
}
},
"page":1,
"pages":3,
"per_page":30,
"total":72
}Imagine that, the same as above. While we may add or remove data points from time-to-time, the calls & logic will all remain the same. That's how we determine if your request is a web view, XMLHttpRequest or API. Magic. Ok not really, but still pretty cool.