Wrts

De Wrts API

Met de Wrts API kun je je eigen programma aan Wrts koppelen. Je kunt dat programma dan lijsten in Wrts laten toevoegen, bekijken, bewerken en ook weer verwijderen. Als je bijvoorbeeld een MSN-bot wilt schrijven die je al chattend je woordjes overhoort, dan kun je daarbij deze API gebruiken.

De Wrts API werkt via het internet. Via een gewone HTTP-verbinding vraag je de informatie op in XML-formaat. (Je kunt de urls ook met je browser bekijken. Dat is een handige manier om de API te verkennen.)

Voor het bekijken van de informatie moet je via HTTP Basic Authentication aangeven wie je bent. Gebruik als gebruikersnaam het e-mailadres van de gebruiker, en gebruik als wachtwoord zijn wachtwoord.

In sommige gevallen moet je ook zelf informatie opsturen, bijvoorbeeld als je een nieuwe lijst wilt toevoegen. In dat geval stuur je een XML-bestand mee via een HTTP POST-verzoek. Let op dat je in dat geval wel de extra header 'Content-Type: application/xml' meestuurt, om aan te geven dat je gegevens in XML-formaat instuurt. Hier is een voorbeeld met Curl:

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

Wrts stuurt na ieder verzoek de HTTP-statuscode 200 terug. Is de opdracht mislukt, dan is dat een andere code. 401 als je moet inloggen, 404 als de lijst niet is gevonden etcetera. In die gevallen krijg je als resultaat ook een XML-bestand met een <error>-tag, met daarin iets meer informatie over wat er verkeerd was:

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

Hieronder volgt een overzicht van de informatie die je kunt opvragen en de opdrachten die je kunt geven. Steeds zie je de HTTP-opdracht die je moet uitvoeren en de url die je moet gebruiken (het getal 1234 in de URL moet je vervangen door de id van de lijst), eventueel het XML-bestand dat je met de opdracht moet insturen en een voorbeeldresultaat. Vragen en opmerkingen zijn altijd welkom, zie het colofon voor de contactinformatie.

Overzicht van alle lijsten van de gebruiker

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

Geeft een overzicht van alle lijsten van de ingelogde gebruiker. Niet alle lijsten staan direct onder <lijst-index>, sommige lijsten staan in een <group>. Deze groep komt overeen met de automatische groepen in het overzicht.

Toekomst-tip: mogelijk wordt de lijstenlijst in de toekomst nog verder onderverdeeld. Zoek om alle lijsten te krijgen naar alle <list>-en onder <list-index> en dieper (XPath: /list-index//list), dan heb je ze allemaal.

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

De inhoud van een lijst

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

Geeft de gegevens van de lijst, een verwijzing naar de trefwoorden die erbij horen en de woorden op de lijst.

Toekomst-tip: mogelijk kan een <word> in de toekomst meer dan één <word-a> etc. hebben, voor bijvoorbeeld verschillende goede antwoorden. Zorg dat je programma hier niet van schrikt, door bijvoorbeeld alleen de eerste <word-a> te gebruiken.

<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>
  
  <!-- als de lijst wordt gedeeld -->
  <shared href="http://www.wrts.nl/api/shared/example">true</shared>
  <download-count>0</download-count>
  
  <!-- als de lijst niet wordt gedeeld -->
  <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>

Een nieuwe lijst maken

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

Stuur de gegevens, de trefwoordverwijzingen en de woorden die je wilt toevoegen. Trefwoorden worden vanzelf aangemaakt als ze nog niet bestaan.

<list>
  <title>Code génial 1</title>
  <lang-a>Frans</lang-a>
  <lang-b>Nederlands</lang-b>
  
  <!-- als de lijst moet worden gedeeld -->
  <shared>true</shared>
  
  <!-- als de lijst niet moet worden gedeeld -->
  <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>

Na het toevoegen krijg je de gegevens van de nieuwe lijst, volgens het standaardformaat (zie hierboven).

<list>... zie lijst bekijken ...</list>

Een lijst bewerken

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

Vervangt de gegevens van de lijst door de ingestuurde gegevens. De formaten zijn hetzelfde als bij het maken van een nieuwe lijst.

<list>... zie lijst maken ...</list>
<list>... zie lijst bekijken ...</list>

Je hoeft niet alle velden mee te sturen: voor ontbrekende onderdelen wordt de oude waarde gebruikt. Als je de woorden niet wilt veranderen stuur je geen <words> mee, als je alleen de titel wilt veranderen stuur je alleen het veld <titel> etcetera. Om het delen van een lijst aan te zetten, stuur je bijvoorbeeld dit:

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

Een lijst verwijderen

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

Verwijdert de lijst en stuurt voor de vorm nog wat XML terug.

<empty-result/>

De overhoorresultaten van een lijst

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

Geeft de resultaten van de overhoorrondes voor deze lijst. Van iedere overhoring worden van de eerste drie foutrondes de fouten weergegeven.

<results href="http://www.wrts.nl/api/lists/1234/results">
  <list href="http://www.wrts.nl/api/lists/1234">
    ... beknopte lijstinformatie, zie overzicht van lijsten ...
  </list>
  
  <result>
    <created-on>2006-01-10T15:19:46+01:00</created-on>
    
    <score>9.6</score>
    <score lang="nl">9,4</score>
    <score lang="en">95%</score>

    <test-method>gedachten</test-method>
    <test-method lang="nl">gedachten</test-method>
    <test-method lang="en">in your mind</test-method>
    <test-method lang="es">pensamientos</test-method>
    <test-method lang="de">Gedankenarbeit</test-method>
    <test-method lang="fr">mentalement</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>
      
      ... nog meer fouten in deze ronde ...
    </round>
    
    ... de volgende twee rondes ...
  </result>
  
  ... nog meer overhoringen ...
</results>

Een nieuw resultaat opslaan

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

Bewaart het resultaat van een overhoring van deze lijst. Geef van de eerste drie overhoorrondes kun de foute antwoorden mee. De score van de overhoring wordt automatisch berekend aan de hand van het aantal goede en foute antwoorden.

test-method is afkomstig uit de lijst {carousel, consonants, firstletter, inyourmind, multiplechoice, shuffle, spelling, test}.

<result>
  <created-on>2006-01-10T15:19:46+01:00</created-on>

  <test-method>test</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>
    
    ... nog meer fouten in deze ronde ...
  </round>
  
  ... de volgende twee rondes ...
</result>

Na het toevoegen krijg je de bijgewerkte resultatenlijst, volgens het standaardformaat (zie hierboven).

<results>... zie overhoorresultaten bekijken ...</results>

De resultaten van een lijst verwijderen

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

Verwijdert alle resultaten voor deze lijst en stuurt het (nu lege) resultatenoverzicht terug.

<results>
  <list href="http://www.wrts.nl/api/lists/1234">
    ... beknopte lijstinformatie, zie overzicht van lijsten ...
  </list>
</results>

Gegevens van de gebruiker bekijken

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

Geeft de gegevens van de ingelogde gebruiker. (Is niet via de API te veranderen, alleen te bekijken.)

<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>
  
  <-- als de deelfunctie is ingeschakeld -->
  <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>

Overzicht van alle trefwoorden van de gebruiker

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

Geeft een overzicht van de trefwoorden van deze gebruiker.

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

Een trefwoord

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

Geeft de gegevens van het trefwoord en een overzicht van de lijsten die bij dit trefwoord horen (in het formaat van het algemene lijstenoverzicht).

<keyword href="http://www.wrts.nl/api/keywords/4">
  <id>4</id>
  <title>6 VWO</title>
  <list-index>... zie overzicht lijsten ...</list-index>
</keyword>

Een nieuw trefwoord maken

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

Maakt het nieuwe trefwoord en stuurt de trefwoordgegevens terug.

<keyword>
  <title>6 VWO</title>
</keyword>
<keyword>... zie trefwoord bekijken ...</keyword>

Een trefwoord bewerken

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

Wijzigt de titel van het trefwoord, en stuurt de nieuwe trefwoordgegevens terug. (Je kunt hier geen lijsten aan een trefwoord koppelen.)

<keyword>... zie trefwoord maken ...</keyword>
<keyword>... zie trefwoord bekijken ...</keyword>

Een trefwoord verwijderen

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

Verwijdert het trefwoord en stuurt voor de vorm nog wat XML terug.

<empty-result/>

Een gedeelde-lijsten-pagina

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

Geeft een overzicht van de gedeelde lijsten die worden aangeboden op dit delen-subdomein. Het lijstoverzicht heeft dezelfde vorm als het algemene lijstenoverzicht van een gebruiker.

<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>... zie overzicht lijsten ...</list-index>
</shared>

    Wrts is een project van De Digitale School · Colofon · Veelgestelde vragen

We werken aan een nieuwe versie van Wrts. Probeer de testversie.