This is where you start appreciating the OPTIMO APIs and we have set up a nice guide for you on how to do it properly. As you spend more time with our APIS, you will feel like you cannot get enough of our APIs which is fair; there is no limit to what you can create using our APIs as a developer. So, hop on!
Now you are probably ready to find out how to make your first booking using our APIs, but not so fast. It will be really helpful to imagine the process you would go through if you were to make a booking in real life. Suppose you want to reserve a place for a surprise birthday party you are planning to throw for your friend. You have to make sure the place will meet certain requirements; number of people it can accommodate, available seating arrangements (a church would be a terrible idea for this), accessibility, if you can afford the prices there and most importantly if the space is free on the date of your friend's birthday, and many more.
So, that is what we are going to do here, and there are different ways you can look at this task. One way to do is to first think of a Venue then find out what are the available Assets you can find there for your requirement. Venue and Assets are in bold letters as they are a couple of key terms and have specific meanings in the OPTIMO system. Venue has its literal meaning; a place or confined area where events happen such as a hotel, a building or multiple buildings, a park, a stadium, etc.
If you refer to our API Reference, under Venues > Venues - List, you will find an endpoint to extract a list of venues. Let's try it out.
GET ../api/v4.1/venues
Sample JSON response:
The response contains key information such as the name of the Venue, a short description, and, in some cases, a URL to the website of the Venue. Once you have picked a Venue by its unique "id", say "416" from the sample response, you then can find an Asset in that Venue. An Asset refers to a facility, resource or branding area. A Venue has a set of Assets of which at least one is a facility.
The API reference, under Venues > Venues / Assets - List, displays the endpoint as /api/v4.1/venues/{id}/assets where we replace {id} with the ID of the venue, 416.
GET ../api/v4.1/venues/416/assets
Sample JSON response:
The response above contains different fields of information on a couple of Assets, two facilities in this case. If you want to narrow down the number of fields, then you can used the fields parameter.
GET ../api/v4.1/venues/416/assets?fields=facility.facilityCategory,facility.name,facility.openingTime,facility.closingTime
A couple of rules here.
The first argument (postfix) added to the URL of the endpoint should be preceded by the symbol '?'.
Multiple fields can be passed as parameters, separated by commas.
A field may be referred to as <type>.<attribute_identifier>; for example facility.name
The sample JSON response which shows only the name of the facility, what kind of facility it is and its open hours:
So, in this episode, we obtained a list of Venues, picked one of them and then we found out what kind of Assets it offered to hold our event. We can try a different path to do the same, in the next section.