Category: API

Endpoint/Route Design

I just found myself in a position where I need to re-write an endpoint to deal with what in hindsight feels like an obvious mistake.

If you are ever writing an endpoint and you’re returning one type of object for one set of requests and a highly-related, but still slightly different object for another set of requests, that is a sign that you probably need to split your one endpoint into two endpoints.

In my case, both use cases are asking the endpoint for a list of the same kind of underlying widget, but they are asking for slightly different ‘snapshots’ of that underlying object.

I’ve partially de-normalized my database when it comes to this foundational (to my application) widget as a way of reducing joins, which means that depending on which view of the widget one is after, a different table is hit.

I started out thinking ‘this route gives me a list of widgets’, but now I’m realizing that I need to proceed under a ‘this route gives me this view of the widgets’ and ‘that route gives me a different view of the widgets’ which means that I always return the exact same type of object across the one route and a different (but always the same for that route) type of object for the second route.

As painful as it is to have to re-work an endpoint (and all of the associated tests), I suspect this is the better option in the long run, and will keep things from getting unnecessarily complicated down the road.

GET Requests

Coming from a non-traditional software engineering background (meaning I didn’t finish a college degree in computer science, or go to a bootcamp), I’ve had to piece together things from disparate sources of information.

I feel like this has largely worked for me, and has meant that I have a different, sometimes better, approach to certain aspects of development.

Unfortunately, I sometimes find out that I’ve got a huge blindspot in an area.

My initial experience with HTTP requests left me with the impression that GET requests are used to get information, and POST requests are used to pass information to the server.

For a variety of reasons, I’ve mostly needed to work with POST requests up to this point, but I do remember an instance where I was working with Google’s translation API, and I was shocked that making a call to translate some text was a POST call rather than a GET call. After all, I was requesting information (a translation) from their service.

As it turns out, there is a lot more going on there than I’d initially realized. GET requests are meant to be cacheable, and idempotent. Because of this, it is generally bad form to pass information in the request body. Everything is supposed to be contained in the URL…which in turn creates a limit in the number of parameters you can pass because there is a limit to the length of the URL that can be passed via a get request (~2,000 characters).

Google needed to be able to pass translation requests with more than 2000 characters to them. Additionally, they don’t want common translations to be cached and then served out to multiple customers. They want to be able to charge each individual customer for each translation, no matter how common the translation is.

There are likely other factors, but those two alone pretty much ensured that using a GET for that translation endpoint was a bad idea.

I found this medium post really helpful if you want a more detail explanation.