Making a reservation

For some trips it is possible to make a reservation. For some trips it is a requirement to make a reservation. In order to make a reservation the Client must make use of all the available information provided.

It starts with getting the available Product (p:product) & Subscription (p:subscription) from the trip-leg that one wants to make a reservation for. Note that if neither is available for a certain trip- leg that it is not possible to make a reservation.

Take this trip-leg for example:

{
  "_links" : {
    "self" : {
      "href" : "https://api.goabout.com/trip-leg/123"
    },
    "http://rels.goabout.com/subscriptions": [ {
      "href": "https://api.goabout.com/subscription/233"
    } ],
    "http://rels.goabout.com/products": [ {
      "href": "https://api.goabout.com/product/21"
    } ],
  },
  "departure" : "2013-12-16T10:12:00.000Z",
  "..." : "...",
  "..." : "...",
}

This indicates that the User has 2 options to make a reservation. One by using a product they are already subscribed to (https://api.goabout.com/subscription/233) and a product they are not yet subscribed to, but could be if they provide the correct information.

Retrieve subscription information

$ curl -H'Authorization: Bearer XYZ' https://api.goabout.com/subscription/233
{
  "productHref" : "https://api.goabout.com/product/23",
  "userHref" : "https://api.goabout.com/user/42",
  "_links" : {
    "self" : {
      "href" : "https://api.goabout.com/subscription/2023"
    }
  }
}

Retrieve product information

$ curl -H'Authorization: Bearer XYZ' https://api.goabout.com/product/23
{
  "name" : "OV-Fiets",
  "logoHref" : "https://goabout.com/pages/product/ov-fiets.png",
  "moreInfoHref" : "https://goabout.com/pages/product/ov-fiets",
  "description" : "Abonnement op de OV-Fietsen die beschikbaar zijn op een groot aantal stations",
  "propertySchema" : "{\"title\": \"OV-Fiets pasnummer\",\"type\": \"object\",\"properties\": {\"cardnumber\": {\"type\": \"string\",\"title\": \"pasnummer\",\"placeholder\": \"123456789\",\"description\": \"Vul hier uw pasnummer voor de OV-Fiets in.\",\"minLength\": 1}},\"required\": [\"cardnumber\"]}",
  "bookPropertySchema" : "{\"title\": \"OV-Fiets reservering\",\"type\": \"object\",\"properties\": {\"cardnumber\": {\"type\": \"string\",\"title\": \"pasnummer\",\"placeholder\": \"123456789\",\"description\": \"Vul hier uw pasnummer voor de OV-Fiets in.\",\"minLength\": 1}},\"required\": [\"cardnumber\"]}"
  "_links" : {
    "self" : {
      "href" : "https://api.goabout.com/product/23"
    }
  },
  "_embedded" : {
    "http://rels.goabout.com/service-provider" : {
      "name" : "NS",
      "href" : "https://goabout.com/pages/agencies/ns",
      "logoHref" : "https://goabout.com/pages/agencies/ns.png",
      "_links" : {
        "self" : {
          "href" : "https://api.goabout.com/agency/12"
        }
      }
    }
  }
}

The bookPropertySchema must be used to determine what fields are needed to fill in to be able to make a reservation. The json-schema can be used to present the User with a form. Validation information is provided also. Note that that is a courtesy to the client and even tough the checks pass, the back-end can still reject the data.

Finding the p:booking-agent

You’ll need to do a POST to the Booking Agent (p:booking-agent), so follow r:booking-agent from the API root (p:root).

Making the reservation

Now that you got all the information, you can POST the data to the booking-agent.

curl -v -d'{
   "tripLegHref":"https://api.goabout.com/trip-leg/123",
   "subscriptionHref":"https://api.goabout.com/subscription/233",
   "properties": {
     "cardnumber": "2257998-73"
   }
}' -H'Authorization: Bearer XYZ' -H'Content-Type: application/json' 'https://api.goabout.com/booking-agent'
{
  "status": "unverified",
  "properties": { "some": "properties", "as-defined": "by-json-schema" },
  "_links": {
    "http://rels.goabout.com/trip-leg" : {
      "href" : "https://api.goabout.com/trip-leg/38548"
    },
    "http://rels.goabout.com/subscription" : {
      "href" : "https://api.goabout.com/subscription/233"
    },
    "self": {
      "href": "https://api.goabout.com/reservation/1022"
    }
  }
}