XML Format

So, keeping in mind all of the basic structures from API Concepts, here's what they look like in XML.

First example

<?xml version="1.0" encoding="UTF-8"?>
<directededge version="0.1">
 <item id='user_1'>
  <link>product_1</link>
  <tag>customer</tag>
  <property name='last name'>Schmidt</property>
  <property name='first name'>Bob</property>
 </item>
 <item id='product_1'>
  <tag>product</tag>
  <property name='artist'>Beatles</property>
  <property name='name'>White Album</property>
 </item>
</directededge>

Here we've got a customer, named Bob Schmidt that's connected to an album called The White Album by Beatles. So we've got two items and one link. Let's start breaking this down a little.

If you imported this to your Directed Edge account using the REST API, you'd have a database with two items.

Before you start sending XML to our server, we recommend passing it through xmllint or similar to make sure that the XML is valid. The most common problem that we see with users that are new to the API is sending invalid XML and then our servers choking on it.

XML header

<?xml version="1.0" encoding="UTF-8"?>

Good old garden variety XML header. We prefer UTF-8, but we shouldn't blow up if you send us other stuff.

directededge element

<directededge version="0.1">

Nothing too exotic here for the moment. This wraps up all of the stuff that you'll send our receive for the moment. Version is always 0.1 for the moment because, well, we're too lazy to bump the version. (Though we'll do better versioning once we're out of beta.)

item element

 <item id='user_1'>

An item is the container for all of the stuff in our database. Exactly what items are is explained in API Concepts.

id attribute

Every item must have an id attribute. That's the handle that we use to refer to the item everywhere. If you want to update or delete the item, you refer to it by its id. You can use any scheme that you want to for creating item identifiers, so long as they're unique. Often something like type_number is convenient.

tag element

Tags are always a child element of an item. Tags can be free form as well. Usually they're things like user, product, page, but they can also be much more specific like, artist, album, sci-fi, etc. You can associate as many tags as you would like with a particular item.

property element

<property name='last name'>Schmidt</property>

Properties are a set of key-value pairs associate with an item. Again, they are free form. You don't need to insert all of the values that you store locally in your database, in fact, most of the time you don't need to associate any at all. These are only useful if you later would like to grab data from the Directed Edge REST API about the items that you're storing there. You can associate as many properties with an item as you like, so long as their names are unique.

name attribute

Every property must have a name attribute. This can be anything that you like, but there may only be one property with a given name per item.