Transcript
Overview: In this lesson, we are going to cover the third part of our POISED testing strategy which is “Interoperability, or Interop for short.”
Note:
For maximum benefit, please view the course video for dynamic demonstrations.
Now that we've looked at parameters and output, it's time to take a look at interoperability, although really these aren't things that you look at in a linear fashion. There's a lot of overlap between output and interop and the parameters and all the other parts of the heuristic.
With interop, an API is nothing by itself.
An API is all about communication. It needs to be communicating in a way that other services or other applications can get the information that they need. One important part of interop to think about is how your parameters are actually formatted and how picky are they about the format. Dates are a very ripe area for exploration in formatting issues.
{
“firstname” : “Jim”,
“Lastname” : “Brown”,
“totalprice” : 111,
“depositpaid” : true,
“bookingdates” : {
“checkin” : “2018-01-01”,
“checkout” : “2019-01-01”
},
“additionalneeds” : “Breakfast”
}
In this case, we have a year, month, date format. What happens if we change it to month, day, year and we send?
“bookingdates” : {
“checkin” : “01-04-2008”,
“checkout” : “2019-01-01”
}
It accepts month, day, year and year, month, day equally.
This is the sort of information that, if it's not being communicated properly in your documentation, can be a real issue for application developers, especially since what if we're in a country that does month, day, year formatting.
For example, the 17th of April, would look like this for non-Americans:
“bookingdates” : {
“checkin” : “17-04-2008”,
“checkout” : “2019-01-01”
}
If we send this, well now that caused a problem with “Invalid Date” results.
With date formatting, you really have to be careful how you're communicating that sort of issue. In my world, if I was the queen of APIs, nobody would pass date strings around. It would all be numeric time stamps.
Anyway, so that's one form of interop to think about. The other one to think about is how you’re returning your information.
Let's look at “Get Booking By Name” for all the bookings that have a last name of Jones
GET > {{rb_url}}/booking?lastname+Jones
All right, we have two. We're getting this back as just the numbers of the booking ID.
[
{
“bookingid” : 2
},
{
“bookingid” : 4
}
]
If I was writing an application that was then trying to display this to customer service or something like that, all I have here is a number. I would have to then take this number and make another call to get “Get Booking By ID” to get the actual information for the parameters. That's two calls where if this was returning the complete information, I would only need to make one call.
On the other hand, if we were doing a large volume of customers and we were getting thousands of customers with each search quest, maybe we wouldn't want to return all of those complete objects in a single call.
There isn't one hard and fast rule about how these sorts of things should be handled, but you need to understand your business needs and what the application developers are looking for.
Basically, you need to communicate about the kind of communication your API is doing. If you have good interoperability, then it's a lot easier for people to use your API and it makes it a better API.
# Code Resource
Quiz:
Note: Chapter 3 has been divided into multiple sub-chapters. You'll find the Quiz on the last sub-chapter, Chapter 3.6. Read on!
