HackathonAPI
From WebOS101
API Details
API
The API is housed in the... wait for it... API.js file. The way it's expected to work is
1. Call API.setService(), passing it one of the SERVICE_* constants in API (API.SERVICE_READ_IT_LATER for now). Ignore the inUser parameter for now, it's not used and should be removed. 2. Call API.verifyAccount(), passing it a User object containing username and password. This user will be stored as part of API from then on, so this HAS to be done before any other API calls are made. 3. Call any other API methods.
Here are the methods, aside from verifyAccount():
- createAccount() - Creates an account on the remote service. Accepts a User object (only username and password must be populated), a callback function when the remote call succeeds and one to call if it fails. The success callback will be passed true, the failure callback will be passed three parameters: error code, error message and error description.
- getAllBookmarks() - Retrieves all bookmarks for the current user from the remote service. Accepts a callback function when the remote call succeeds and one to call if it fails. The success callback will be passed an array of Bookmark objects, the failure callback will be passed three parameters: error code, error message and error description.
- addBookmark() - Adds a single bookmark to the remote service. Accepts a Bookmark object, a callback function when the remote call succeeds and one to call if it fails. The success callback will be passed null, the failure callback will be passed three parameters: error code, error message and error description.
- markBookmarkRead() - Marks a single bookmark as read on the remote service. Accepts a Bookmark object (only the url attribute is required), a callback function when the remote call succeeds and one to call if it fails. The success callback will be passed null, the failure callback will be passed three parameters: error code, error message and error description.
Note that all the methods are non-blocking (asychronous).
Model objects
The model objects are contained in the API.js file as well. They are:
User {
username
password
bookmarks[]
toString()
}
Bookmark {
itemID
title
url
timeAdded
readStatus
tags[]
toString()
toJSON()
}
The above is just the structure, they get instantiated like any other JS object. The toJSON() method in Bookmark returns a JSON representation of the Bookmark in a form suitable for sending to a remote service (at least in the case of ReadItLater).
Function testing using Poster in Firefox
The following are tests Frank performed earlier today to ensure the functions work as expected:
Get All Bookmarks (HTTP GET): URL: https://readitlaterlist.com/v2/get Parameters:
username=xxx password=yyy apikey=xxx tags=1
Add A Bookmark (HTTP POST, application/x-www-form-urlencoded, parameters encoded in POST body): URL: https://readitlaterlist.com/v2/send Parameters:
username=xxx
password=yyy
apikey=xxx
new={"0":{"url":"http://google.com","title":"Google"}}
Mark A Bookmark Read (HTTP POST, application/x-www-form-urlencoded, parameters encoded in POST body): URL: https://readitlaterlist.com/v2/send Parameters:
username=xxx
password=yyy
apikey=xxx
read={"0":{"url":"http://google.com","title":"Google"}}
Verify an account (HTTP GET): URL: https://readitlaterlist.com/v2/auth Parameters:
username=xxx password=yyy apikey=xxx
HTTP response code indicates valid (200) or invalid (401)
Create an account (HTTP GET): URL: https://readitlaterlist.com/v2/signup Parameters:
username=xxx password=yyy apikey=xxx
HTTP response code indicates OK (200) or problem (X-Error gives extended info). The library class abstracts most of this though, so this is just FYI at this point.
Rate Limits
This is copied from the ReadItLater site because I think it's important we keep it in mind... if this app gets popular we could have a problem, specifically on the 10,000 calls per hour limit...
The API has two separate rate limits. These dictate how many calls can be made to the server within a given time. Enforcing rate limits prevents a single app or user from overwhelming the server. The response codes will tell you if you've hit your limit. Your application should be looking for these and if it encounters a rate limit status code, it should back off until it hits the reset time. Ignoring these codes may cause your access to be disabled.
User Limit Each user is limited to 220 calls per hour. This should be very sufficient for most users as the average user only makes changes to their list periodically. To ensure the user stays within this limit, make use of the send method for batching requests.
API Key Limit Each application is limited to 10000 calls per hour. If your application grows to be popular and requires to be whitelisted, please contact me. If you are adding RIL support to an existing application with a large user base and think you might hit this limit right off the bat, please contact me.
Miscellaneous Notes
- On the ReadItLater UI, marking a bookmark as read seems to be akin to delete... there's no explicit delete operation that I can see, and when you mark one as read it's not displayed any longer.
