What are Challenges with our APIs?

by Daniel Lübke

At the end of 2023 I gave two talks – one at APICon in Berlin and the other one at W-JAX in Munich. The talks consisted of 17 questions regarding API development and governance, which I discussed, gave examples for, and gave attendees the opportunity to rate themselves via a small Web application. Yes, it was the first talk in which I actively encouraged my audience to use their mobile phones! While each attendee could see their answers and as a result their API development profile (you can see it as a very short assessment), I could (and discuss) show the aggregated results at the end of my presentation.

These talks were interesting for two reasons: First, I tried a completely new, interactive format, which aimed to make my audience reflect about what they are currently doing and where it would make sense to invest for improvement first, instead of giving them even more things to think about. The feedback and discussions after the talk were great and insightful – and there were many more than after other talks.

Secondly, and that is the main topic of this blog post, the aggregated results of the answers are very interesting. The 17 questions were concerned with 3 dimensions of API development: product, platform and process. So, let’s have a look at the top rated 3 questions. According to the attendees, they agreed most with the following statements:

  • We can prototype an API within a week. (76% of possible points)
  • We are driven by concepts not tools. (73% of possible points)
  • We know all clients for each of the APIs we are offering. (69% of possible points)

I find these answers interesting because they would be a definite improvement compared to experiences I made in many projects and organizations. All these three questions are from the platform category, so there might be some bias because more API platform people might attend API talks and conferences in general. However, I am happy that these topics are highly rated. Especially the question whether a prototype can be built within a week covers many facets: it implicitly checks for the development environment, API design and implementation skills and many other facets of the development process.

Some of the worst rated questions are interesting as well:

  • There is an adequate training offer for each role or another equivalent means of learning the required skills. (48%)
  • We have defined a clear lifecycle each of our APIs. (50%)
  • It is defined who requires which know-how. (54%)

All three of these questions are in the category “organization”. I think it is very important that all these questions relate to foundations of making an API program – or any API development – a success. If you do not qualify people to do the tasks at hand, then people will eventually fail or at least underperform. If you have not defined a lifecycle for your APIs you will face problems when you must introduce breaking changes. If you have not defined which know-how is required, you cannot organize trainings (see worst rated question) and you probably lack clear assignment of responsibilities.

Although many important aspects of API development have been rated very positively by my talks’ attendees, I think the problem areas indicated by the answers are very severe. We as the API community need to focus on clear definition of roles & responsibilities, adequate training, and after all those years lobby for API life-cycle management. The latter is a bit worrying because life-cycle management is an issue from a time where APIs were still called services and SOA was the buzzword of the day. It indicates that concepts are still more difficult than technologies, and that by renaming services to APIs and using HTTP or Restful HTTP instead SOAP we haven’t mastered the important underlying conceptual questions. One source of information are design patterns, e.g., the Patterns for API Design (Discount Voucher, On Amazon), which contain a category of evolution patterns to address some but not all life-cycle challenges.

If you want some more ideas about API life-cycle management, please consider to subscribe to the blog updates below. I wrote more about this topic in the coming weeks.

<<< Previous Blog Post
Why is API Life-Cycle Important?
Next Blog Post >>>
Asynchronous Continuations in Camunda 7

To stay up to date, we invite you to subscribe to our newsletter and receive notifications whenever a new blog post has been published! You can of course unsubscribe from these notifications anytime.