Web Services Examples
So, now that you've been through the documentation on the API Concepts, XML Format and REST API, let's take a look at a few practical examples of working with the Directed Edge webservices.
For these examples we'll be using the command line tool curl to upload XML to the webservices.
Contents
- 1 Importing a database
- 2 Exporting a database
- 3 Adding an item
- 4 Updating an item
- 5 Adding a tag to an item
- 6 Adding a link to an item
- 7 Adding a property to an item
- 8 Add several tags / properties / links to an item
- 9 Removing a tag from an item
- 10 Removing a link from an item
- 11 Retrieving an item
- 12 Deleting an item
- 13 Finding related items
- 14 Doing personalized recommendations
Importing a database
Let's start with a very simple database with three users (with the IDs user1, user2 and user3) and three products (with the IDs product1, product2 and product3).
<?xml version="1.0" encoding="UTF-8"?>
<directededge version="0.1">
<item id="user1">
<tag>user</tag>
<link>product1</link>
<link>product2</link>
</item>
<item id="user2">
<tag>user</tag>
<link>product3</link>
</item>
<item id="user3">
<tag>user</tag>
<link>product2</link>
</item>
<item id="product1">
<tag>product</tag>
</item>
<item id="product2">
<tag>product</tag>
</item>
<item id="product3">
<tag>product</tag>
</item>
</directededge>
Curl Command (Download XML):
This imports the structure above into the exampledb database.
Exporting a database
Curl Command:
Produces:
<?xml version="1.0" standalone="yes"?>
<directededge version="0.1">
<item id="user1">
<tag>user</tag>
<link>product1</link>
<link>product2</link>
</item>
<item id="user2">
<tag>user</tag>
<link>product3</link>
</item>
<item id="user3">
<tag>user</tag>
<link>product2</link>
</item>
<item id="product1">
<tag>product</tag>
</item>
<item id="product2">
<tag>product</tag>
</item>
<item id="product3">
<tag>product</tag>
</item>
</directededge>
Which is what we imported just above.
Adding an item
Adds a user with the ID user4 to the database.
<?xml version="1.0" encoding="UTF-8"?>
<directededge version="0.1">
<item id="user4">
<tag>user</tag>
</item>
</directededge>
Curl Command (Download XML):
Updating an item
Here we update the item above, but this time add the property city. This overwrites all current contents of the item.
<?xml version="1.0" encoding="UTF-8"?>
<directededge version="0.1">
<item id="user4">
<tag>user</tag>
<property name="city">Berlin</property>
</item>
</directededge>
Curl Command (Download XML):
Adding a tag to an item
Here we add the tag Berliner to the user that we created / updated in the previous sections. As noted in the XML Format description, here we're allowed to omit the item's ID.
<?xml version="1.0" encoding="UTF-8"?>
<directededge version="0.1">
<item>
<tag>Berliner</tag>
</item>
</directededge>
Curl Command (Download XML):
Adding a link to an item
This creates a link from our recently created user to product3. Again, since we're updating the item we can omit the item ID.
<?xml version="1.0" encoding="UTF-8"?>
<directededge version="0.1">
<item>
<link>product3</link>
</item>
</directededge>
Curl Command (Download XML):
Adding a property to an item
Sets the value of the property country to Germany.
<?xml version="1.0" encoding="UTF-8"?>
<directededge version="0.1">
<item>
<property name="country">Germany</property>
</item>
</directededge>
Curl Command (Download XML):
Add several tags / properties / links to an item
Just like you can add single tags, properties or links to an item, you can also add (or remove) several at a time:
<?xml version="1.0" encoding="UTF-8"?>
<directededge version="0.1">
<item>
<tag>German</tag>
<property name="first name">Matthias</property>
<property name="last name">Schmidt</property>
<link>product2</link>
</item>
</directededge>
Curl Command (Download XML):
Removing a tag from an item
Just like we could add a tag to an item incrementally, we can remove a tag (or property, or link) by uploading the same content to the remove sub-resource.
<?xml version="1.0" encoding="UTF-8"?>
<directededge version="0.1">
<item>
<tag>Berliner</tag>
</item>
</directededge>
Curl Command (Download XML):
Removing a link from an item
And now we can do the same with removing the link to product3:
<?xml version="1.0" encoding="UTF-8"?>
<directededge version="0.1">
<item>
<link>product3</link>
</item>
</directededge>
Curl Command (Download XML):
Retrieving an item
Now that we've made a number of changes to the item that we've been working with, let's see what the current state of it in the database is:
Curl Command:
Produces:
<?xml version="1.0" standalone="yes"?>
<directededge version="0.1">
<item id="user4">
<tag>German</tag>
<tag>user</tag>
<link>product2</link>
<property name="first name">Matthias</property>
<property name="last name">Schmidt</property>
<property name="city">Berlin</property>
<property name="country">Germany</property>
</item>
</directededge>
Deleting an item
And now let's clear out the item we've been working with from the database.
Curl Command:
Let's get the related items for product1:
Curl Command:
Gives us all related items:
<?xml version="1.0" standalone="yes"?>
<directededge version="0.1">
<item id="product1">
<related>product2</related>
<related>user1</related>
<related>user3</related>
</item>
</directededge>
Hmm, well, that's not quite what we wanted, but have no fear, this is where the tags query attribute comes in handy:
Curl Command:
And now we get back just items with the product tag:
<?xml version="1.0" standalone="yes"?>
<directededge version="0.1">
<item id="product1">
<related>product2</related>
</item>
</directededge>
Doing personalized recommendations
Note that when we want to do personalized recommendations we use the recommended pseudo-resource rather than related. Our servers do a little different of a sort of magic for producing personalized recommendations than are used to find related products or pages.
Curl Command:
Here are the personalized recommendations for user3.
<?xml version="1.0" standalone="yes"?>
<directededge version="0.1">
<item id="user3">
<recommended>user1</recommended>
<recommended>product2</recommended>
<recommended>product1</recommended>
</item>
</directededge>
But here we also get a user in the result set — just as above we want to specify the tags that we're interested in:
Curl Command:
Which now gives us only product results:
<?xml version="1.0" standalone="yes"?>
<directededge version="0.1">
<item id="user3">
<recommended>product2</recommended>
<recommended>product1</recommended>
</item>
</directededge>
So, now we get just products back, but user3 is already connected to product2 — meaning we assume that they've already purchased or rated it, so we don't actually want that in the result set. So let's throw in the excludeLinked=true.
Curl Command:
Now we get only things tagged product and none of the ones that the user already has a connection to:
<?xml version="1.0" standalone="yes"?>
<directededge version="0.1">
<item id="user3">
<recommended>product1</recommended>
</item>
</directededge>
And there we have the (admittedly short) list of personalized recommendations for user3.