Kill your API: the burger analogy

The other day I had a chat with the folks working on the OpenAPI initiative and I explained a trick that some of us in enterprises use to get greater speeds and scalability out of our API’s. At first, this may seem like complete sacrilege to those who are a stickler for standards but if you allow me to explain using a simple analogy, you may see how this can be useful…

The ‘Burger Analogy’

Say for instance your computer has to place an order to a restaurant. You would need to send a REQUEST in the format for that item to the restaurant. So if in this case, I want a ‘cheeseburger’, I would send the ‘content-type: food/cheeseburger’ format so they know what is being requested with the ID of my order and the restaurant would send back [bread,lettuce,tomato,meat,sauce,bread] .

Now since they know what I requested, do you think I have to send additional data telling them the return format is also ‘food/cheeseburger‘? Of course not! That makes no sense! Naturally, I’m expecting ‘food/cheeseburger’… that’s what I sent in as my order! I actually would be very pissy if they sent back ‘food/taco’ (well not that pissy… but you get the idea).

Getting What You Ordered

This is what I explained to the OpenAPI initiative. In API’s we send two headers:

• CONTENT-TYPE: a header to say what data we are REQUESTING with.
• ACCEPT: a header to say what data we are RESPONDING with.

But over 90% of API’s ALWAYS return what is requested! So, this is incredibly redundant. Why are we doing all this additional processing? Well it’s because we are trying to cover 100% of all use cases rather than just automating for 90% and then coding for the exceptions as they occur… as we should be doing.

So of these HEADERS, which dictate FORMAT, only one is needed: Content-Type.

But what about GET, OPTIONS or DELETE?

You can fudge and use CONTENT-TYPE. Using one HEADER for everything makes it easier to automate, easier to code, easier to process and easier to request. This creates simplicity for our AJAX and API calls. No creating a dozen different ways to call things. Just ONE-WAY to call EVERYTHING and ONE-WAY to PROCESS.

So one create an AJAX call like this


$.ajax({
type: POST,
url: '`+window.url+`/v0.1/`+path+`' ,
data: JSON.stringify(jsonData),
headers:{
'Content-Type': 'application/json'
},
success: function(json) {
...
},
error: function(jqXHR, textStatus, errorThrown) {
...
},
));


Usages in Frameworks

This is already being used in several frameworks to gain speed advantages. One framework where you can find it immediately in is Grails:
Grails 3.0 ignores the HTTP Accept header unless you add a grails.mime.use.accept.header = true setting to your application.groovy file. In other words, withFormat () will be completely unaffected by the Accept header without that setting.

This change was added officially to Grails 3.0 after a suggestion made by myself on the forums mentioning how one didn’t have to use the ACCEPT header at all.

Returning a Different Format

What if I need to send JSON to get a resource and process that resource back as a PDF? Simple… Send the ACCEPT header from the controller/method. That way there is nothing to process but your client can receive a different CONTENT-TYPE and your docs can reflect it.

In the example below I show a Spring-Boot Controller Method where I return the ACCEPT header:

   @RequestMapping(method=RequestMethod.GET,"/greeting")

   public Greeting greeting(@RequestParam(value="name", defaultValue="World") String name) {

       response.addHeader("Accept","application/pdf");

        ...                                             

}

Simplicity… Going Against Convention

I know I’m going to get a 50/50 reaction; I generally do when I show things that greatly increase speed and scale but go in the face of convention. But for those who are always looking to get the most out of their environments, this is one of the tricks I have used for a few years now. ?