Are You Doing This With Your API?

DZone 's Guide to

Are You Doing This With Your API?

A Zone Leader provides an image of something near his residence, which acts as a metaphor to bad API design.

· Microservices Zone ·
Free Resource

question mark

Not all API design is created equal!

Consider the following image:

It was taken at a location not too far from my residence. A few years ago, a company headquarters was relocated to space just to the west of where this photo was taken. The picture above provides a view of the east-most entrance/exit to the property and shows that the necessary time was taken to create a sidewalk entrance — including the brail-based "warning track".

You may also like: Secrets to Great API Design

The problem is, the sidewalk goes no more than a few feet.

My question to you ... are you doing this with your API?

Creating an API With No Practical Use

The sidewalk captured in the image serves no practical purpose. Having been in place for three or four years now, I feel like it is safe to say there are no plans to make the sidewalk longer.

In my years working in the API space, I have witnessed similar situations within APIs that are built and maintained by clients.

On occasion, I was reading through the Swagger API documentation and noticed an end-point that I did not recall getting used by any of the known clients accessing the private API. When I asked about the URI that sparked my interest, I was told that the end-point had been created "just in case the business needs something like that."

While this approach was likely not intentional, with the feature team deciding to go ahead and finish out some functionality that leverages other code already in place, the team seemed to end up violating the "Cart Before the Horse" anti-pattern.

In all likelihood, there is a good chance that when the business formally asks for the functionality already created - the implementation would likely require updates. As a result, there is a chance that more time will be required to complete this feature than if the team had waited before starting development.

Creating An API Because It Was Required

In the case of the sidewalk, I would guess (and hope) the reason the project added the sidewalk was due to some regulation or law that required a safe exit for pedestrians crossing the entrance/exit to the facility.

Translating this to an API, a similar example is a requirement that URIs must have a DELETE method if a POST or PUT method exists in the API. Believe it or not, I have seen this as a corporate directive as well.

The reason is similar to what was noted above but in a somewhat reverse nature. Here, the directive came from IT leadership that became frustrated that additional work was required when other applications wanted to use an existing API.

In this example, the original feature teams followed best practices and only created end-points that were needed and required for their client applications to function. A short time later, other systems wanted to connect into the same API but needed more functionality — like the ability to perform DELETE requests. Out of frustration, a new mandate was added to require DELETE methods to exist, if a POST or PUT method is available... just in case, another system requires this functionality.

Upon hearing this information, at a different client than the last example, I had questions that I wanted to ask the group making the mandate. Questions I never was able to ask, but it did make me wonder if some of those decision-makers decided to get into the construction business and become a part of the project which built the sidewalk that is at the heart of my article.

Duplicating an Existing API

If I were to take a picture toward the north of the sidewalk photo, there would (of course) be traffic that could be easily seen. Beyond that, one would see the same path that I often take on nice days when heading to my local gym for a workout. Unlike the smaller sidewalk in the photo, the pavement north of the image is larger and accommodating my jog to the gym or even a bicycle ride as well.

Had the sidewalk continued, it would have duplicated an existing path that is already in place... and quite accommodating to walkers, joggers, and cyclists. The landscape is far more suited for pedestrian traveling as well.

This reminds me of cases where a new API is duplicating an existing API. This is something I have encountered on larger projects ... including my current project. In my example, another team failed to keep up with the Swagger API documents which provided insight into the URIs available for the service. As a result, the team worked in isolation to create something which already existed.

When the PR came to me for review, I pointed them to the work that had already been completed and tested by another team. Just like in the example with the sidewalk, the duplicate API was not as robust and well-designed as the original API. Unfortunately, more time was required to remove the duplicate code and have their client team make adjustments as well.


I noticed the area in the photo once the intersection was built. In my mind, I asked myself why the east side of the entrance/exit included a sidewalk to nowhere. I waited to see if someone was going to attempt to introduce more concrete to make a usable path — knowing the landscape to the east was going to be challenging to complete. After several years, this never happened, which allowed the situation to become an inspiration to me.

As developers, we are often provided the option of creativity for completing tasks assigned to us. We must remember there is an inherent responsibility to make sure we are doing the right thing — especially with our APIs:

  • Avoid adding URIs to your API which do not have a valid use case.
  • Challenge directives for adding unnecessary URIs to your API.
  • Before introducing new URIs to your API — make sure you are not duplicating an existing URI.

Have a great day!

Further Reading

Designing Your First REST API — Part 1

Top 5 REST API Design Problems

REST API Best Practices — Design Examples From Java and Spring Web Services

microservice architecture ,api ,antipattern ,microservices ,api best practices ,api design

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}