We’ve already talked about a few characteristics of a good API but let’s explore one a little. APIs should be easy to use right? Well, sure … but what does that mean? What could be hard about /orderSpecial? Not much. We know what the parameters are: number, size, and drink. These are documented and well known. Could this be used in incorrectly? But what exactly does the ‘extras’ mean? Does saying extras=ketchup mean “Please give add a few ketchup packets for my fries” or does it mean “Please add ketchup to my burger” or even stranger “Please add ketchup to my drink”? OK, chances are that last one isn’t a request we’re going to ever see but it illustrates the point. Previously, we assumed extras was added to the burger. That’s all it was – an assumption. The fast food crew should perform the action in a consistent way each time. Which is it? We won’t know until the response comes back and we’re either excited or disappointed, or angry if ketchup is in our Coke!
Even though our previous post showed how our fast food API example had some characteristics of a good API, it still falls short. Yes, the operation itself is pretty clear-cut and we talked a little about reusability, but we’ve come to a place where the designer didn’t consider the fact that the extras option turns out to be ambiguous once released to the public. Thus the API can be misused and can ultimately lead to user frustration. Rusty Russel points out this subtlety of an API in his post How Do I Make This Hard to Misuse? So what’s the ‘extras’ score? I’d put it around a 6 or 7. Pretty good, but it can definitely be improved. This doesn’t scream ‘back to the drawing board’; it’s merely an opportunity to improve upon and extend the API.
Even good APIs will need to adapt. In this case, ‘extras’ isn’t clear enough. We need to extend the API while still maintaining a minimal footprint. In other words, the API needs to be clearer without becoming long and difficult. What are our options? We could leave the API as-is and let convention rule. Unfortunately that’s what got us here in the first place. We could add another parameter and keep ‘extras’. Does that address our issue? It still has the problem of ‘extras’ being ambiguous even if we add another parameter. What we will do is remove ‘extras’ and replace it with something else. We STILL have another problem. This API is already in the wild! There may be some customers already using the extras parameter. If we change it immediately, we may break customer software. We need to maintain support but deprecate ‘extras’ usage and allow enough time for adoptability among the development community. We’ll propose adding two new optional parameters which should disambiguate ‘extras’. Let’s call them sandwichAddon and mealExtras. Even though our API has had to be lengthened it’s a better model for the real world and should do the job of keeping user frustration at a low, increasing adoption.