Difference between revisions of "Web Services Examples"

From the Directed Edge Developer Base
Jump to: navigation, search
(→‎Adding an item)
 
(20 intermediate revisions by the same user not shown)
Line 4: Line 4:
  
 
== Importing a database ==
 
== 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'').
 +
 +
<source lang="xml">
 +
<?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>
 +
</source>
 +
 +
{{CurlPut|database}}
 +
 +
This imports the structure above into the ''exampledb'' database.
 +
 +
== Exporting a database ==
 +
 +
{{CurlGet}}
 +
 +
Produces:
 +
 +
<source lang="xml">
 +
<?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>
 +
</source>
 +
 +
Which is what we imported just above.
  
 
== Adding an item ==
 
== Adding an item ==
  
−
== Retrieving an item ==
+
Adds a user with the ID ''user4'' to the database.
 +
 
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<directededge version="0.1">
 +
  <item id="user4">
 +
    <tag>user</tag>
 +
  </item>
 +
</directededge>
 +
</source>
 +
 
 +
{{CurlPut|user4|/items/user4}}
  
 
== Updating an item ==
 
== Updating an item ==
 +
 +
Here we update the item above, but this time add the property ''city''.  This overwrites all current contents of the item.
 +
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<directededge version="0.1">
 +
  <item id="user4">
 +
    <tag>user</tag>
 +
    <property name="city">Berlin</property>
 +
  </item>
 +
</directededge>
 +
</source>
 +
 +
{{CurlPut|user4-update|/items/user4}}
  
 
== Adding a tag to an item ==
 
== 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.
 +
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<directededge version="0.1">
 +
  <item>
 +
    <tag>Berliner</tag>
 +
  </item>
 +
</directededge>
 +
</source>
 +
 +
{{CurlPut|tag|/items/user4/add}}
  
 
== Adding a link to an item ==
 
== 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.
 +
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<directededge version="0.1">
 +
  <item>
 +
    <link>product3</link>
 +
  </item>
 +
</directededge>
 +
</source>
 +
 +
{{CurlPut|link|/items/user4/add}}
  
 
== Adding a property to an item ==
 
== Adding a property to an item ==
 +
 +
Sets the value of the property ''country'' to ''Germany''.
 +
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<directededge version="0.1">
 +
  <item>
 +
    <property name="country">Germany</property>
 +
  </item>
 +
</directededge>
 +
</source>
 +
 +
{{CurlPut|property|/items/user4/add}}
 +
 +
== 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:
 +
 +
<source lang="xml">
 +
<?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>
 +
</source>
 +
 +
{{CurlPut|several|/items/user4/add}}
  
 
== Removing a tag from an item ==
 
== 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.
 +
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<directededge version="0.1">
 +
  <item>
 +
    <tag>Berliner</tag>
 +
  </item>
 +
</directededge>
 +
</source>
 +
 +
{{CurlPut|tag|/items/user4/remove}}
  
 
== Removing a link from an item ==
 
== Removing a link from an item ==
 +
 +
And now we can do the same with removing the link to ''product3'':
 +
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<directededge version="0.1">
 +
  <item>
 +
    <link>product3</link>
 +
  </item>
 +
</directededge>
 +
</source>
 +
 +
{{CurlPut|link|/items/user4/remove}}
 +
 +
== 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:
 +
 +
{{CurlGet|/items/user4}}
 +
 +
Produces:
 +
 +
<source lang="xml">
 +
<?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>
 +
</source>
  
 
== Deleting an item ==
 
== Deleting an item ==
 +
 +
And now let's clear out the item we've been working with from the database.
 +
 +
{{CurlGet|/items/user4|argument=-X DELETE}}
  
 
== Finding related items ==
 
== Finding related items ==
 +
 +
Let's get the related items for ''product1'':
 +
 +
{{CurlGet|/items/product1/related}}
 +
 +
Gives us all related items:
 +
 +
<source lang="xml">
 +
<?xml version="1.0" standalone="yes"?>
 +
 +
<directededge version="0.1">
 +
  <item id="product1">
 +
    <related>product2</related>
 +
    <related>user1</related>
 +
    <related>user3</related>
 +
  </item>
 +
</directededge>
 +
</source>
 +
 +
Hmm, well, that's not quite what we wanted, but have no fear, this is where the ''tags'' query attribute comes in handy:
 +
 +
{{CurlGet|/items/product1/related\?tags&#61;product}}
 +
 +
And now we get back just items with the ''product'' tag:
 +
 +
<source lang="xml">
 +
<?xml version="1.0" standalone="yes"?>
 +
 +
<directededge version="0.1">
 +
  <item id="product1">
 +
    <related>product2</related>
 +
  </item>
 +
</directededge>
 +
</source>
  
 
== Doing personalized recommendations ==
 
== 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.
 +
 +
{{CurlGet|/items/user3/recommended}}
 +
 +
Here are the personalized recommendations for ''user3''.
 +
 +
<source lang="xml">
 +
<?xml version="1.0" standalone="yes"?>
 +
 +
<directededge version="0.1">
 +
  <item id="user3">
 +
    <recommended>user1</recommended>
 +
    <recommended>product2</recommended>
 +
    <recommended>product1</recommended>
 +
  </item>
 +
</directededge>
 +
</source>
 +
 +
But here we also get a user in the result set &mdash; just as above we want to specify the tags that we're interested in:
 +
 +
{{CurlGet|/items/user3/recommended\?tags&#61;product}}
 +
 +
Which now gives us only product results:
 +
 +
<source lang="xml">
 +
<?xml version="1.0" standalone="yes"?>
 +
 +
<directededge version="0.1">
 +
  <item id="user3">
 +
    <recommended>product2</recommended>
 +
    <recommended>product1</recommended>
 +
  </item>
 +
</directededge>
 +
</source>
 +
 +
So, now we get just products back, but ''user3'' is already connected to ''product2'' &mdash; 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''.
 +
 +
{{CurlGet|/items/user3/recommended\?tags&#61;product\&excludeLinked&#61;true}}
 +
 +
Now we get only things tagged ''product'' and none of the ones that the user already has a connection to:
 +
 +
<source lang="xml">
 +
<?xml version="1.0" standalone="yes"?>
 +
 +
<directededge version="0.1">
 +
  <item id="user3">
 +
    <recommended>product1</recommended>
 +
  </item>
 +
</directededge>
 +
</source>
 +
 +
And there we have the (admittedly short) list of personalized recommendations for ''user3''.

Latest revision as of 22:43, 14 January 2014

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.

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):

$ curl -T database.xml https://exampledb:password@webservices.directededge.com/api/v1/exampledb

This imports the structure above into the exampledb database.

Exporting a database

Curl Command:

$ curl https://exampledb:password@webservices.directededge.com/api/v1/exampledb

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):

$ curl -T user4.xml https://exampledb:password@webservices.directededge.com/api/v1/exampledb/items/user4

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):

$ curl -T user4-update.xml https://exampledb:password@webservices.directededge.com/api/v1/exampledb/items/user4

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):

$ curl -T tag.xml https://exampledb:password@webservices.directededge.com/api/v1/exampledb/items/user4/add

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):

$ curl -T link.xml https://exampledb:password@webservices.directededge.com/api/v1/exampledb/items/user4/add

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):

$ curl -T property.xml https://exampledb:password@webservices.directededge.com/api/v1/exampledb/items/user4/add

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):

$ curl -T several.xml https://exampledb:password@webservices.directededge.com/api/v1/exampledb/items/user4/add

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):

$ curl -T tag.xml https://exampledb:password@webservices.directededge.com/api/v1/exampledb/items/user4/remove

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):

$ curl -T link.xml https://exampledb:password@webservices.directededge.com/api/v1/exampledb/items/user4/remove

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:

$ curl https://exampledb:password@webservices.directededge.com/api/v1/exampledb/items/user4

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:

$ curl -X DELETE https://exampledb:password@webservices.directededge.com/api/v1/exampledb/items/user4

Finding related items

Let's get the related items for product1:

Curl Command:

$ curl https://exampledb:password@webservices.directededge.com/api/v1/exampledb/items/product1/related

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:

$ curl https://exampledb:password@webservices.directededge.com/api/v1/exampledb/items/product1/related\?tags=product

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:

$ curl https://exampledb:password@webservices.directededge.com/api/v1/exampledb/items/user3/recommended

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:

$ curl https://exampledb:password@webservices.directededge.com/api/v1/exampledb/items/user3/recommended\?tags=product

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:

$ curl https://exampledb:password@webservices.directededge.com/api/v1/exampledb/items/user3/recommended\?tags=product\&excludeLinked=true

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.

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