Difference between revisions of "REST API"

From the Directed Edge Developer Base
Jump to: navigation, search
(basic structure)
 
(37 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
The Directed Edge [[Wikipedia:REST|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]].
 
The Directed Edge [[Wikipedia:REST|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 [[Wikipedia:Hypertext Transfer Protocol#Request_methods|HTTP methods]] GET, PUT, POST and DELETE on various resources.  We'll explain below which of these are allowed.
+
REST APIs allow for using the [[Wikipedia:Hypertext Transfer Protocol#Request_methods|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:
 
Let's have a look at an example URL:
  
−
<nowiki>https://username:password@webservices.directededge.com/api/v1/wikipedia/</nowiki>
+
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/}}</tt>
  
−
This is the URL for the wikipedia database.  Many of the elements are constant &mdash; notably the host name, and the ''api/v1'' sections.  We'll break down the other components in the following sections.
+
This is the URL for the wikipedia database.  Many of the elements are constant &mdash; 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 ==
 
== 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 ==
 
== 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:
 +
 +
<tt>{{URL||user:password|@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/}}</tt>
 +
 +
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 ==
 
== Database resource ==
 +
 +
: ''Example of Wikipedia database''
 +
 +
<tt>{{URL|username:password@webservices.directededge.com/api/v1/|wikipedia|/}}</tt>
 +
 +
The database is the mothership of items &mdash; 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.
 +
 +
Also note that your database name is the same as your user name.
  
 
=== HTTP GET ===
 
=== 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 ===
 
=== 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'''.
 +
 +
=== HTTP POST ===
 +
 +
This is used for updating the database in batch.  The key [[Recommendation parameters|query parameter]] is '''updateMethod'''.  Valid values are:
 +
 +
* '''replace''': This is the default.  This means that the posted content should replace everything in the database.
 +
* '''add''': This means that the posted content should be added to the already existing content in the database.
 +
* '''subtract''': This means that the values should be ''subtracted'' from the database.  In this case, subtraction means that for an individual item, any values that are specified will be removed (e.g. to remove a tag) from the items present in the post.  If an item does not contain any additional tags in this data, then the item itself will be removed.
 +
 +
These would be, respectively:
 +
 +
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;replace}}</tt>
 +
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;add}}</tt>
 +
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;subtract}}</tt>
 +
 +
=== HTTP DELETE ===
 +
 +
'''Warning''':  This clears all data from the database and resets it to its default empty condition.  Use with caution.
  
 
== Item resource ==
 
== Item resource ==
 +
 +
: ''Example of the '"Miles Davis" item in the Wikipedia database''
 +
 +
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/|Miles%20Davis|/}}</tt>
 +
 +
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 ===
 
=== 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 ===
 
=== 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 POST ===
 +
 +
This is used for updating items (potentially incrementally).  The key [[Recommendation parameters|query parameter]] is '''updateMethod'''.  Valid values are:
 +
 +
* '''replace''': This is the default.  This means that the posted content should replace the item.
 +
* '''add''': This means that the posted content should be added to the already existing content.
 +
* '''subtract''': This means that the values should be ''subtracted'' from the database.  In this case, subtraction means that any values that are specified will be removed (e.g. to remove a tag) from the items present in the post.
 +
 +
These would be, respectively:
 +
 +
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;replace}}</tt>
 +
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;add}}</tt>
 +
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;subtract}}</tt>
  
 
=== HTTP DELETE ===
 
=== HTTP DELETE ===
  
−
=== Add and remove sub-resources ===
+
Removes the item from the database.  This also removes all incoming links (from other items) pointing to this item.
 +
 
 +
== Related / recommended resources ==
 +
 
 +
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|related}}</tt>
 +
<tt>{{URL|username:password@webservices.directededge.com/api/v1/somestore/items/user12345/|recommended}}</tt>
 +
 
 +
Now we get to the business end of the API &mdash; 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:''
 +
 
 +
[[Image:Amazon-related.png]]
 +
 
 +
''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:''
 +
 
 +
[[Image:Amazon-recommendations.png]]
  
−
==== HTTP PUT ====
+
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 / recommended resources ==
+
''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 ===
 
=== HTTP GET ===
 +
 +
So, now that you know what ''related'' and ''recommended'' are about, fetching their content is pretty trivial.  You just send a get request to our servers and the top items will be returned in an [[XML Format|XML]] list.  '''The order matters here'''.  The top items are at the top of the list and ranked in descending order.
  
 
=== Query Parameters ===
 
=== Query Parameters ===
 +
 +
There are a couple of ways that you can shape the results that are returned from ''related'' or ''recommended'' queries.
 +
 +
==== excludeLinked query parameter ====
 +
 +
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|excludeLinked&#61;true}}</tt>
 +
 +
This parameter is most often used in conjunction with ''recommended'' queries.  You remember from our [[API Concepts]] that a link is any relationship between items?  Well, usually when you're recommending items to a user, you want to avoid recommending things that they've already interacted with &mdash; products that they've already bought, for instance.
 +
 +
So, there you just add the handy ''excludeLinked'' parameter to the end of the query and the user will only see recommendations for things they haven't already bought / rated / clicked on / etc.
 +
 +
==== tags query parameter ====
 +
 +
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|tags&#61;product,page}}</tt>
 +
 +
Again, from the [[API Concepts]] you should be familiar with ''tags'' within the Directed Edge data model.  Most users of the API have broadly things that generalize to ''users'' and ''products'', and you often only want to recommend items matching one of those tags.
 +
 +
So, to drive the recommended products for a given user, you'd just slap on the ''tags=product'' to the end of the query string and presto, you'll only get results that have the ''product'' tag.
 +
 +
You can pass in as many tags as you like.  They're logically connected via a ''logical or'' &mdash; meaning that products that have ''any'' of the tags that you specify will be included in the results.
 +
 +
==== maxResults query parameter ====
 +
 +
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|maxResults&#61;5}}</tt>
 +
 +
This one's really simple:  it specifies the number of results that you're interested in receiving from ''related'' or ''recommended'' queries.  If you're feeling particularly charitable, set this to the number of items that you actually display on your site and save our servers the trouble of finding results that you're not interested in.
 +
 +
==== ''type''Weight ====
 +
 +
If you've used different [[XML Format#type attribute|link types]] in your data, you can specify different link weights for the different link types in the query.  For example, if you used the type ''viewed'' and ''linked'' you could do:
 +
 +
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|viewedWeight&#61;5&amp;linkedWeight&#61;10}}</tt>
 +
 +
Of note here is that weights for items with an unspecified link type can be specified with <tt>defaultWeight=1</tt> (where 1 can be substituted for the appropriate weight).
 +
 +
Also note that once you have specified one or more ''type''Weights, only those types which have been assigned a weight will be included in the computations.
 +
 +
==== Additional query options ====
 +
 +
The above are the most common query parameters.  Our full list of supported query parameters, which have similar usage as the options above, is here:
 +
 +
* '''[[Recommendation parameters]]'''

Latest revision as of 20:16, 3 July 2014

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/items/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.

Also note that your database name is the same as your user name.

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.

HTTP POST

This is used for updating the database in batch. The key query parameter is updateMethod. Valid values are:

  • replace: This is the default. This means that the posted content should replace everything in the database.
  • add: This means that the posted content should be added to the already existing content in the database.
  • subtract: This means that the values should be subtracted from the database. In this case, subtraction means that for an individual item, any values that are specified will be removed (e.g. to remove a tag) from the items present in the post. If an item does not contain any additional tags in this data, then the item itself will be removed.

These would be, respectively:

https://username:password@webservices.directededge.com/api/v1/wikipedia?updateMethod=replace https://username:password@webservices.directededge.com/api/v1/wikipedia?updateMethod=add https://username:password@webservices.directededge.com/api/v1/wikipedia?updateMethod=subtract

HTTP DELETE

Warning: This clears all data from the database and resets it to its default empty condition. Use with caution.

Item resource

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

https://username:password@webservices.directededge.com/api/v1/wikipedia/items/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 POST

This is used for updating items (potentially incrementally). The key query parameter is updateMethod. Valid values are:

  • replace: This is the default. This means that the posted content should replace the item.
  • add: This means that the posted content should be added to the already existing content.
  • subtract: This means that the values should be subtracted from the database. In this case, subtraction means that any values that are specified will be removed (e.g. to remove a tag) from the items present in the post.

These would be, respectively:

https://username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?updateMethod=replace https://username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?updateMethod=add https://username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?updateMethod=subtract

HTTP DELETE

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

Related / recommended resources

https://username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related https://username:password@webservices.directededge.com/api/v1/somestore/items/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:

Amazon-related.png

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:

Amazon-recommendations.png

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

So, now that you know what related and recommended are about, fetching their content is pretty trivial. You just send a get request to our servers and the top items will be returned in an XML list. The order matters here. The top items are at the top of the list and ranked in descending order.

Query Parameters

There are a couple of ways that you can shape the results that are returned from related or recommended queries.

excludeLinked query parameter

https://username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?excludeLinked=true

This parameter is most often used in conjunction with recommended queries. You remember from our API Concepts that a link is any relationship between items? Well, usually when you're recommending items to a user, you want to avoid recommending things that they've already interacted with — products that they've already bought, for instance.

So, there you just add the handy excludeLinked parameter to the end of the query and the user will only see recommendations for things they haven't already bought / rated / clicked on / etc.

tags query parameter

https://username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?tags=product,page

Again, from the API Concepts you should be familiar with tags within the Directed Edge data model. Most users of the API have broadly things that generalize to users and products, and you often only want to recommend items matching one of those tags.

So, to drive the recommended products for a given user, you'd just slap on the tags=product to the end of the query string and presto, you'll only get results that have the product tag.

You can pass in as many tags as you like. They're logically connected via a logical or — meaning that products that have any of the tags that you specify will be included in the results.

maxResults query parameter

https://username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?maxResults=5

This one's really simple: it specifies the number of results that you're interested in receiving from related or recommended queries. If you're feeling particularly charitable, set this to the number of items that you actually display on your site and save our servers the trouble of finding results that you're not interested in.

typeWeight

If you've used different link types in your data, you can specify different link weights for the different link types in the query. For example, if you used the type viewed and linked you could do:

https://username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?viewedWeight=5&linkedWeight=10

Of note here is that weights for items with an unspecified link type can be specified with defaultWeight=1 (where 1 can be substituted for the appropriate weight).

Also note that once you have specified one or more typeWeights, only those types which have been assigned a weight will be included in the computations.

Additional query options

The above are the most common query parameters. Our full list of supported query parameters, which have similar usage as the options above, is here:

Retrieved from "https://developer.directededge.com/index.php?title=REST_API&oldid=341"