Boom test uitgevers
Account Manager API

Thijs van der Vossen, thijs@fngtps.com, Fingertips.

The Boom Account Manager API is a REST web service for managing Boom test uitgevers user accounts and creating purchases. The following tutorial uses curl on the command line to show you how it works.

Getting user account information

From /users/[user_id].xml you can GET user information including the credit balance.

$ curl --user thijs:secret -i https://account.boomtestuitgevers.nl/users/1.xml
  
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Content-Length: 520

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <admin type="boolean">false</admin>
  <balance type="integer">74</balance>
  <blocked type="boolean" nil="true"></blocked>
  <created-at type="datetime">2006-12-08T14:48:00+00:00</created-at>
  <deleted type="boolean">false</deleted>
  <email>thijs@fngtps.com</email>
  <id type="integer">1</id>
  <name>Thijs van der Vossen</name>
  <phone></phone>
  <updated-at type="datetime">2008-04-21T18:40:45+01:00</updated-at>
  <username>thijs</username>
</user>

In case you don’t know your id, you can get the information for the user you’ve authenticated as from /users/me.xml

Listing products

You can get a list of all available products from /products.xml

$ curl --user thijs:secret -i https://account.boomtestuitgevers.nl/products.xml
  
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Content-Length: 899

<?xml version="1.0" encoding="UTF-8"?>
<products type="array">
  <product>
    <created-at type="datetime">2008-04-21T13:19:38+01:00</created-at>
    <description>Scoring en normering van de AGS-30, NVE, NVE-K, en de SCARED.</description>
    <id type="integer">1</id>
    <location>https://score.boomtestuitgevers.nl</location>
    <status>published</status>
    <title>Scoring</title>
    <updated-at type="datetime">2008-04-21T21:09:00+01:00</updated-at>
  </product>
  <product>
    <created-at type="datetime">2008-04-21T21:07:12+01:00</created-at>
    <description>De nieuwe toetsen voor Technisch Lezen en Hoofdrekenen van Teije de Vos.</description>
    <id type="integer">2</id>
    <location>https://svt.boomtestuitgevers.nl</location>
    <status>published</status>
    <title>Schoolvaardigheidstoetsen</title>
    <updated-at type="datetime">2008-04-21T21:07:12+01:00</updated-at>
  </product>
</products>

Creating a purchase

You can create an purchase by POSTing the purchase data to /purchases.xml

The product_id is the id of the product registered in the Account manager.

The title and a description should allow the user to easily identify the administration. The administration_path needs to point to the primary information about this administration within the product. In other words, joining the product location and the administration_path should result in a valid url for the administration resource.

The instrument_title should contain the full title of the instrument used for this administration. The instrument_path needs to point to the primary information about the instrument within the product. In other words, joining the product location and the instrument_path should result in a valid url for the instrument resource.

The credit amount will be subtracted from the balance of the user you’ve authenticated as. Even though a value is required, you can use 0 for free administrations.

You’ll get a ‘201 Created’ response when the purchase has been created. The id of the created purchase can be found as part of the resource url in the Location header.

$ curl --user thijs:secret -i -d purchase[product_id]=1 -d \
purchase[title]="Afname van de SVT2 voor Bobje" -d \
purchase[description]="Afname van de SVT2 voor Bobje aangemaakt op 2 mei 2008." -d \
purchase[administration_path]=/administrations/12 -d \
purchase[instrument_title]="Schoolvaardigheidstoets 2" -d \
purchase[instrument_path]=/instruments/2 -d \
purchase[amount]=8 \
https://account.boomtestuitgevers.nl/purchases.xml

HTTP/1.1 201 Created
Location: https://account.boomtestuitgevers.nl/purchases/1165
Content-Type: application/xml; charset=utf-8
Content-Length: 663

<?xml version="1.0" encoding="UTF-8"?>
<purchase>
  <administration-path>/administrations/12</administration-path>
  <amount type="integer">8</amount>
  <created-at type="datetime">2008-04-21T21:20:56+01:00</created-at>
  <description>Afname van de SVT2 voor Bobje aangemaakt op 2 mei 2008.</description>
  <id type="integer">1165</id>
  <instrument-path>/instruments/2</instrument-path>
  <instrument-title>Schoolvaardigheidstoets 2</instrument-title>
  <product-id type="integer">1</product-id>
  <title>Afname van de SVT2 voor Bobje</title>
  <updated-at type="datetime">2008-04-21T21:20:56+01:00</updated-at>
  <user-id type="integer">1</user-id>
</purchase>

When the purchase could not be created because of missing parameters or insufficient credit, you’ll get a ‘422 Validation Error’ response with the error messages in the body.

$ curl --user thijs:secret -i -d purchase[product_id]=9 -d \
purchase[amount]=999 https://account.boomtestuitgevers.nl/purchases.xml

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/xml; charset=utf-8
Content-Length: 411

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Instrument path can't be blank</error>
  <error>Title can't be blank</error>
  <error>Instrument title can't be blank</error>
  <error>Product can't be blank</error>
  <error>Amount U beschikt niet over voldoende eenheden voor deze afname.</error>
  <error>Administration path can't be blank</error>
  <error>Description can't be blank</error>
</errors>

Doing things a little different

When using the API from your application you may want to do some things a little different depending on the environment you’re using.

Instead of using the .xml extension, you can also set the Accept header to ‘application/xml’ which is a little cleaner.

$ curl --user thijs:secret -H 'Accept: application/xml' \
https://account.boomtestuitgevers.nl/me

Instead of form data encoded as ‘application/x-www-form-urlencoded’ or ‘multipart/form-data’, you can send your request parameters as xml. Set the Content-Type request header to ‘application/xml’ and POST or PUT xml in the body of your request.

$ curl --user thijs:secret \
-H 'Accept: application/xml' -H 'Content-Type: application/xml' -d "
<administration>
  <questionnaire_id>2</questionnaire_id>
  <subject>bobje</subject>
  <enter>scale_scores</enter>
</administration>" https://scoring.boomtestuitgevers.nl/administrations.xml -i