Difference between revisions of "REST API"
(→API Authentication) |
(switch to url template) |
||
| Line 5: | Line 5: | ||
Let's have a look at an example URL: | Let's have a look at an example URL: | ||
| − | + | {{URL|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. | 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. | ||
| Line 25: | Line 25: | ||
: ''Example of Wikipedia database'' | : ''Example of Wikipedia database'' | ||
| − | + | {{URL|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. | 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. | ||
| Line 41: | Line 41: | ||
: ''Example of the '"Miles Davis" item in the Wikipedia database'' | : ''Example of the '"Miles Davis" item in the Wikipedia database'' | ||
| − | + | {{URL|username:password@webservices.directededge.com/api/v1/wikipedia/|Miles%20Davis|/}} | |
=== HTTP GET === | === HTTP GET === | ||
Revision as of 05:33, 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.
Contents
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/
