Blog article
See all stories »

Should APIs be Pre-made or Deli style?

Sandwich

I was out looking for a sandwich for lunch the other day and found myself faced by two options; I could either go to the convenience store and pick up a pre-made sandwich or go to the deli and have one made for me.

The pre-made option sounds simple, but choice is usually limited to the imagination of the sandwich maker. Going to a deli to have a sandwich made offers freedom of choice, but I’d have to deal with queues of people trying to make up their minds about which ingredients they want (including me when I get there).

From the stores perspective, the pre-made option is easy – display what’s on offer and let the customer pick one; it’s quick and simple. However, a reduced choice may push customers towards the Deli. The Deli owner can offer his customers choice, but at the cost of extra staff to make sandwiches based on each customers requirement. The little effort required by customers and possible delays could push customers to the convenience store for the “best fit” option.

Producing read APIs could follow a similar approach.

Pre-made. As an API producer, using the inside-out-approach, I could decide “what” my consumers need and make a range of specific endpoints for them to consume. If one endpoint does not cover all their requirements, they could compose the data they need by consuming a number of my APIs; extracting the bits needed from each. This will give me full control over my API implementation and allow me to optimize them for better performance. Eventually, however, my consumers will complain and ask for more “specific” APIs to meet their needs. In my experience, this is all too often the reality.

Deli style. As an API producer, using the outside-in-approach, I could offer my consumers the ability to select which elements in my API domain should be returned. This would require me to provide proper documentation to explain my domain and I’d need to implement the selection logic (and consequences) in my services. Like the Deli needs to maintain the cost of a sandwich maker, I’d need to accept the cost of maintaining this logic and implementing it for new elements in the future. The benefit, of course, is that my API will offer complete customization, making it as consumable as possible by more than one consumer – a desirable trait for APIs.

There is an alternative – I could provide the full data object in the response. In other words, provide all the data elements of the object being modeled and let the customer extract the values needed, ignoring the rest (pun intended). This approach creates less work for the producer – only one simple endpoint is required per object. The effort is passed to the consumer, similar to the Deli-style approach, only the selection of elements is made on the response instead of providing input into the request. Taking advantage of HATEAOS will reduce the payload size and offer discoverability but could force the consumer to perform the composition in order to get all the data elements required.

So, as API producers we have options. We can offer our consumers flexibility through choosing data elements before or after request, or we can offer them what we think they need – the choice is ours. Each approach has its merits and its consequences, but they are nonetheless choices.

I’ve worked on APIs that follow all three of these approaches. The Deli style approach offers benefit to the consumer and reduces payload. The challenge comes in selecting data elements for the request input in a hierarchical data structure. The approach we took was simple; use dot.notation to identify the data elements just as you would when reading the JSON response.

Image provided by Pexels.com

3710
External | what does this mean?
This content is provided by an external author without editing by Finextra. It expresses the views and opinions of the author.

Comments: (3)

Ketharaman Swaminathan
Ketharaman Swaminathan - GTM360 Marketing Solutions - Pune 12 October, 2018, 10:521 like 1 like

Nice post. Keen on knowing how the third approach will work if the given user is not entitled "all the data elements of the object being modeled" according to prevailing security and privacy laws and contractual obligations in force. Also, how this approach is different from the traditional approach of dumping an entire (large) file in a staging area. From what I understand, one of the advantages of the API versus file dump approach is that an API is expected to have a much smaller "payload" than dumped files, thus making API the preferred choice for realtime / high performance ask-get use cases (as against batch use cases).

Craig Hughes
Craig Hughes - Danske Bank - Copenhagen 15 October, 2018, 15:18Be the first to give this comment the thumbs up 0 likes

Thanks for the questions Ketharaman.

Your first question regarding the sensitivity of data being shared. We currently use the scopes within a JWT to define if sensitive portions of the data elements can be presented in the response. Quite simply, if an authenticated user does not have the scope (authorization) required for a portion of the data within the API response, then these elements are omitted. For obvious reasons, supporting documentation needs to expand on this. 

Secondly, you mentioned that using the third option could result in a very large dataset - which could be compared to a file dump. It is possible that this could be the consequence if you allow your consumer to “select all”. However, there are approaches you can deploy to avoid this, including:

  • Paging (limiting the response to a maximum number of records)
  • Hyperlinking (or HATEOAS) - providing links to internal entities instead of the data (supporting discovery)
  • Or option 2 - the Deli-style approach when requesting lists of data - let the consumer decide which elements make sense in a list in order to find the single entity being sought.

Thanks,

Craig

Ketharaman Swaminathan
Ketharaman Swaminathan - GTM360 Marketing Solutions - Pune 15 October, 2018, 15:35Be the first to give this comment the thumbs up 0 likes

@Craig Hughes: TY for the clarifications. 

Craig Hughes

Craig Hughes

Enterprise Architect API

Danske Bank

Member since

06 Sep

Location

Copenhagen

Blog posts

10

Comments

3

More from Craig

This post is from a series of posts in the group:

API

More generic posts and blogs relating with Application Programming Interfaces (APIs) including Open Banking and PSD2


See all