Difference between revisions of "REST API"

Revision as of 06:39, 23 May 2009

The Directed Edge REST API is a fairly simple way of modeling a collection of items and the relationships between them. These relationships are used as the basis for finding similar items or delivering personalized recommendations to a user. Information is encoded using our XML Format using notions from the API Concepts.

REST APIs allow for using the HTTP methods GET, PUT, POST and DELETE on various resources. Resources are just normal URLs organized hierarchically. In our case there is the database, items and things you can do with items (query, update, etc.).

Let's have a look at an example URL:

https://username:password@webservices.directededge.com/api/v1/wikipedia/

This is the URL for the wikipedia database. Many of the elements are constant — notably the host name, and the "api/v1" sections. We'll break down the other resources and the methods allowed on them in the following sections.

HTTP and HTTPS

The Directed Edge API allows for both HTTP and secured HTTPS connections. HTTPS tends to incur a slightly higher latency since setting up the connection is more involved.

API Authentication

We use HTTP Basic authentication exclusively at the moment. HTTP Basic just means a user name and password that you stick at the front of the URL, just like if you were connecting to an FTP site. For example:

https://user:password@webservices.directededge.com/api/v1/wikipedia/Miles%20Davis/

When your account was created for use with the Directed Edge recommendation engine you should have been send a user name and a (usually freakishly long) password. In general the user name is the same as the database name. We can reset your password for you at any time, but can not provide your current password if you lose it.

Database resource

Example of Wikipedia database

https://username:password@webservices.directededge.com/api/v1/wikipedia/

The database is the mothership of items ‐ it's just one big set of items and those items are connected to other stuff and whatnot. The methods that you typically want to run on a database are importing and exporting it, which map conveniently to the GET and PUT methods. Check out the documentation on the XML Format to figure out what the data you send should look like.

HTTP GET

Used to dump the database including all items, links, properties and tags to XML. You can use this to grab a snapshot of your database at any point in time. However, please do this sparingly since it naturally hits the database pretty hard.

HTTP PUT

Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our XML Format. Note that this will overwrite all content currently in your database.

Item resource

Example of the '"Miles Davis" item in the Wikipedia database

https://username:password@webservices.directededge.com/api/v1/wikipedia/Miles%20Davis/

Items are the bread and butter of the Directed Edge recommendations engine. As noted in the API Concepts, everything is an item. Items contain must have an identifier, which is the part highlighted in the URL above. That can be anything you want, but naturally, when used as part of the resource name, must be URL encoded. (The language bindings handle that for you.)

HTTP GET

This retrieves the item with all of its tags, properties and links. See XML Format for a description of the data you'd expect here.

HTTP PUT

Updates or creates an item overwriting all of its current contents. The item identifier used in the XML must match the resource name that you're updating or creating. This may contain tags, properties and links and will overwrite all of the current data associated with this item. Items that link to this item will not be affected.

HTTP DELETE

Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.

Add and remove sub-resources

Examples of adding or removing bits of the "Miles Davis" item in the Wikipedia database

https://username:password@webservices.directededge.com/api/v1/wikipedia/Miles%20Davis/add https://username:password@webservices.directededge.com/api/v1/wikipedia/Miles%20Davis/remove

Here we break a little bit from traditional REST dogma by adding pseudo-resources that let you do partial updates of resources. The pure at heart can still stick to the item resource above an rely on it for updating items wholesale.

The add and remove sub-resources allow you to add / remove tags, links or properties incrementally. You don't have to worry about race conditions between pulling down the content of a resource and updating it in the database.

The typical use cases are adding a tag to a given item, or removing a property.

The XML Format docs also explain that you may omit certain parts of the typical item XML for convenience.

HTTP PUT

In the case of calling add any tags, properties or links that you've put in the XML will be incrementally updated in the database. If those values already exist, they'll simply be ignored.

Calling remove, similarly, does an incremental removal of those tags, links or properties from the database. This one is the quirkiest to think about because you're doing a PUT to a REST resource and it removes stuff, but in practice this is a convenient way of removing little bits of the content of a given item.

Related / recommended resources

https://username:password@webservices.directededge.com/api/v1/wikipedia/Miles%20Davis/related https://username:password@webservices.directededge.com/api/v1/somestore/user12345/recommended

Now we get to the business end of the API — the reason that you're here in the first place. Here again we break a little from the typical REST dogma by creating resources for information that's computed on the fly.

The first thing to note here is that related and recommended are subtlety different.

Related is used for finding similar things. For instance, a friend finder in a social network would use the related method. Similarly, if you wanted to find similar products in an online store, again, related is the thing that you're looking for.

Here's what these look like in Amazon:

Recommended on the other hand uses a magic of a slightly different sort to find personalized recommendations. You know, "Hi Bob, here are some books that we think you'll like..." Again we'll defer to Amazon:

Amazon showing personalized recommendations:

The item used for the recommended query should usually be a user. Recommended is also usually used in conjunction with the exlcludeLinked query parameter mentioned below.

Related and recommended form the core of the mathematical heavy lifting that Directed Edge does for your site. In a sense, everything else that you can do with the Directed Edge database is built up to getting the most out of these recommendations.

HTTP GET

Query Parameters