Wrds

Wrds API

The Wrts API can be used to connect your own software to Wrts, Your program can then add lists to Wrts, and view, edit and remove them. If, for example, you want to create an MSN-bot which tests your words while chatting, you can use this API for that.

You can access the Wrts API with standard HTTP requests. You can send and receive information in XML format. (You can also access the API urls with your browser: this is a nice way to explore the API.)

For most actions, you must authenticate via HTTP Basic Authentication. Use the email address and password of the user to log in.

Some of the API functions require you to send data to our server, for example, to add a new word list. Send this data as an XML document as the data of your HTTP POST request. Make sure to send the header 'Content-Type: application/xml', to tell our API that you are sending XML data. An example with Curl: 

curl -u test@example.com:test -H 'Content-Type: application/xml' -d '<list>...' url

Wrts will respond with HTTP status 200. If your request could not be processed, Wrts will return a HTTP error code: 401 if you didn't log in, 404 if we could not find your list et cetera. In these cases our server will also return an XML document with an <error> element, with more information about what went wrong:

<error status="404">List 1234 not found.</error>

This overview will show you which information you can request using our API and which actions you can execute. We list the HTTP method and the url that you should use (be sure to replace the example number 1234 in the urls with the ID of your own list). Where necessary, we also give an example of the XML document you should send and an example of the XML response you will get.

If you have any question or comment, please send us an e-mail! See our contact information.

List of all word lists of the user

GET http://www.wrts.nl/api/lists

Returns a list of all word lists of the authenticated user. Not every list appears directly under <list-index>, some lists are in a <group>. These groups correspond to the groups in the user's overview.

For forward compatibility: we may add extra groupings to the list of lists, so to make sure that you get every list you should search for all <list> elements in <list-index> and deeper (XPath: /list-index//list).

<list-index>
  <list href="http://www.wrts.nl/api/lists/1234">
    <id>1234</id>
    <title>Code génial 1</title>
    <lang-a>Frans</lang-a>
    <lang-b>Nederlands</lang-b>
    <created-on>2005-10-27T21:46:37+02:00</created-on>
    <updated-on>2006-03-31T12:50:03+02:00</updated-on>
    <word-count>11</word-count>
    <shared href="http://www.wrts.nl/api/shared/example">true</shared>
    <download-count>0</download-count>
    <result-count href="http://www.wrts.nl/api/lists/1234/results">16</result-count>
  </list>
  ...
  <group>
    <title>Na Klar!</title>
    <list>...</list>
    ...
  </group>
  ...
</list-index>

A word list

GET http://www.wrts.nl/api/lists/1234

Returns the attributes of the word list, pointers to the keywords to which the list belongs and the words on the list.

For forward-compatibility: a <word> element may contain more than one <word-a>, <word-b> et cetera, for example to have alternative answers. Make sure your application does not break if this happens: for example, always use the first <word-a> you see and ignore the others.

<list href="http://www.wrts.nl/api/lists/1234">
  <id>1234</id>
  <title>Code génial 1</title>
  <lang-a>Frans</lang-a>
  <lang-b>Nederlands</lang-b>
  <created-on>2005-10-27T21:46:37+02:00</created-on>
  <updated-on>2006-03-31T12:50:03+02:00</updated-on>
  
  <!-- if the list is shared -->
  <shared href="http://www.wrts.nl/api/shared/example">true</shared>
  <download-count>0</download-count>
  
  <!-- if the list is not shared -->
  <shared>false</shared>
  
  <result-count href="http://www.wrts.nl/api/lists/1234/results">16</result-count>
  
  <keywords>
    <keyword href="http://www.wrts.nl/api/keywords/31">Frans</keyword>
    <keyword href="http://www.wrts.nl/api/keywords/32">Klas 2</keyword>
    ...
  </keywords>
  
  <words>
    <word>
      <word-a>bonjour</word-a>
      <word-b>hallo</word-b>
    </word>
    ...
  </words>
</list>

Create a new word list

POST http://www.wrts.nl/api/lists

Send the attributes, the keywords and the words that you want to add. New keywords will be created if they do not yet exist.

<list>
  <title>Code génial 1</title>
  <lang-a>Frans</lang-a>
  <lang-b>Nederlands</lang-b>
  
  <!-- if the list should be shared -->
  <shared>true</shared>
  
  <!-- if the list should not be shared -->
  <shared>false</shared>
  
  <keywords>
    <keyword>Frans</keyword>
    <keyword>Klas 2</keyword>
    ...
  </keywords>
  
  <words>
    <word>
      <word-a>bonjour</word-a>
      <word-b>hallo</word-b>
    </word>
    ...
  </words>
</list>

The API will return the data of the new list (see the description of this format above).

<list>... see 'A word list' ...</list>

Update an existing word list

POST http://www.wrts.nl/api/lists/1234

Replaces the attributes of the list by the new attributes. See 'creating a list' for the format of the XML document.

<list>... see 'Create a new word list' ...</list>

<list>... see 'A word list' ...</list>

You don't have to provide all attributes: only send the attributes you want to change. For example, if you don't want to change the words you do not send a <words> element, if you only want to change the title you just send the <title> element et cetera.

Example: to enable the sharing of a list, you would send:

<list>
  <shared>true</shared>
</list>

Delete a list

DELETE http://www.wrts.nl/api/lists/1234
or POST http://www.wrts.nl/api/lists/1234/delete

Deletes the list and returns an empty XML response:

<empty-result/>

The practice results of a list

GET http://www.wrts.nl/api/lists/1234/results

Returns the results of previous practice sessions for this list. For every session, we return the wrong ansers of the first three rounds.

<results href="http://www.wrts.nl/api/lists/1234/results">
  <list href="http://www.wrts.nl/api/lists/1234">
    ... some attributes of the list (see the list overview) ...
  </list>
  
  <result>
    <created-on>2006-01-10T15:19:46+01:00</created-on>
    <score>7</score>
    <test-method>toets</test-method>
    <test-order>ab</test-order>
    <seconds>152</seconds>
    
    <round number="1">
      <correct-count>4</correct-count>
      <wrong-count>5</wrong-count>
      <error>
        <question>de vakantie</question>
        <correct-answer>der Urlaub</correct-answer>
        <wrong-answer>die Urlaub</wrong-answer>
      </error>
      
      ... other errors in this round ...
    </round>
    
    ... the second and third round ...
  </result>
  
  ... more practice results ...
</results>

Delete the practice results of a list

DELETE http://www.wrts.nl/api/lists/1234/results
or POST http://www.wrts.nl/api/lists/1234/results/delete

Deletes the results of previous practice sessions of this list and returns the (empty) result overview.

<results>
  <list href="http://www.wrts.nl/api/lists/1234">
    ... some attributes of the list (see the list overview) ...
  </list>
</results>

User data

GET http://www.wrts.nl/api/users/me

Returns the attributes of the authenticated user. (You can only view this information via the API, it can only be changed via the website.)

<user href="http://www.wrts.nl/api/users/12">
  <email>test@example.com</email>
  <name>Voorbeeldgebruiker</name>
  <speech>true</speech>
  
  <created-on>2005-10-27T21:46:36+02:00</created-on>
  <updated-on>2006-03-18T21:30:43+01:00</updated-on>
  <last-seen-on>2006-04-03T18:33:31+02:00</last-seen-on>
  
  <-- if list sharing is enabled -->
  <share href="http://www.wrts.nl/api/shared/example">
    <subdomain>example</subdomain>
    <title>Mijn lijsten</title>
    <text>Dit is mijn verhaal.</text>
    <url>http://example.wrts.nl/</url>
  </share>
</user>

Overview of all keywords of the user

GET http://www.wrts.nl/api/keywords

Returns the list of keywords of the authenticated user.

<keyword-index>
  <keyword href="http://www.wrts.nl/api/keywords/12">3 VMBO</keyword>
  <keyword href="http://www.wrts.nl/api/keywords/3">5havo</keyword>
  <keyword href="http://www.wrts.nl/api/keywords/4">6 VWO</keyword>
  ...
</keyword-index>

A keyword

GET http://www.wrts.nl/api/keywords/1234

Returns the attributes of the keyword and a list of the word lists that belong to this keyword (in the same format as in the list overview).

<keyword href="http://www.wrts.nl/api/keywords/4">
  <id>4</id>
  <title>6 VWO</title>
  <list-index>... see the list overview ...</list-index>
</keyword>

Create a keyword

POST http://www.wrts.nl/api/keywords

Creates the keyword and returns the keyword properties.

<keyword>
  <title>6 VWO</title>
</keyword>

<keyword>... see 'a keyword' ...</keyword>

Update a keyword

POST http://www.wrts.nl/api/keywords/1234

Changes the title of the keyword and returns the updated keyword properties.

<keyword>... see 'create a keyword' ...</keyword>

<keyword>... see 'a keyword' ...</keyword>

Delete a keyword

DELETE http://www.wrts.nl/api/keywords/1234
or POST http://www.wrts.nl/api/keywords/1234/delete

Deletes the keyword and returns an empty XML document.

<empty-result/>

A list sharing site.

GET http://www.wrts.nl/api/shared/example

Returns an overview of the lists that are shared via this sharing site (replace example with the subdomain). The list overview has the same format as the overview of the lists of a user.

<shared href="http://www.wrts.nl/api/shared/example">
  <title>Mijn lijsten</title>
  <text>Dit is mijn verhaal.</text>
  <url>http://example.wrts.nl/</url>
  
  <list-index>... see the list overview ...</list-index>
</shared>

    Wrds is a project of The Digital School · Colophon · Frequently Asked Questions