The grid
The grid

We need to talk about APIs one last time. APIs are great. They connect businesses, enable innovations, improve efficiency, and provide the backbone of e-commerce. But the way we do APIs is broken beyond repair.

I see it all the time. You are a small to mid-size business, and you can’t be bothered by API expertise. It is not your job to master APIs. So you put your API together following your favorite influencer and using (preferably free) off the shelf products.

Or you are a large enterprise. You do not even know how many APIs you have. There is…


Image for post
Image for post

It has been two years since I left Apiary and started the Good API venture. I did it because I wanted to practice what we were preaching. I desired to be in the trenches with API practitioners. I hoped to help companies on their API journey, the critical part of the Digital Transformation.

And it went great! Over the two years, I have worked with many amazing companies like Adidas, Deutsche Post DHL Group or Ytica (recently acquired by Twilio) to establish and fast-track their API programs.

And while APIs are no longer the new kool-aid, most of the companies…


Image for post
Image for post

supermodel.io — Data Model of Your Domain, API, and Application. Solved.

Since I have started the Good API consulting company, I have worked on hundreds of API designs across many domains. From simple, straightforward APIs to modeling the most complex domain interfaces that exist, one pattern started to emerge — the lack of information about semantics and structure of data.

Small, fast-moving organizations usually do not bother with a formal definition of data models. Larger enterprises frequently carry the burden of arcane, canonical data model which no longer works with the actual software development paradigms. …


Image for post
Image for post

Are you building an API?

Here is the idea: If you have never heard about the REST architectural style constraints and their implication on the properties of the resulting distributed system and you do not want to (or can’t) educate yourself, use GraphQL.

UPDATE

I had a keynote on this topic at Nordic APIs Platform Summit 2018. In this talk, I introduce the Framework for evaluation API Paradigms based on Constraints and Properties. I have tried to incorporate the constructive feedback on this article and provide as many unbiased insights as possible.

Keep in mind that is still a critical review


Image for post
Image for post

The way APIs are currently developed, consumed and maintained is neither scalable nor sustainable. What seems to be a machine to machine communication is, in fact, a mechanical Turk relying upon human engineers and tech writers imperatively integrating and tightly coupling distributed systems. The human role is expensive, extremely slow and error-prone.

Furthermore, APIs providers are willingly developing and providing their API functionality in silos isolated from each other, in fear of becoming a commodity. …


Often, when designing an API, I reference to Richardson Maturity Model, and, lately to Amundsen Maturity Model. The desired norm I recommend to Good API clients is to attain level two of both Richardson and Amundsen’s Maturity Models (reasonable minimum for most of the APIs). But why does it matter? What are these level anyway? And if I have an existing API how to do a maturity assessment? Let’s dive into the maturity of APIs.

Image for post
Image for post
Photo by Tobias Fischer on Unsplash

Richardson Maturity


As a part of my Good API ventures, I’ve had the pleasure to spend the past six months working for the adidas as API Designer and Evangelist.

Image for post
Image for post

Some of you might be wondering why one of the biggest shoemakers in the world needs APIs. But at the verge of the digital transformation where every company is a software company, APIs play a critical role in enabling interoperability, improving efficiency, reducing costs and communicating with partners and customers.


Image for post
Image for post

Every service and system deserves its API.

Building an API became just another mundane item on our checklist. Perfect documentation, unified developer’s experience, great design, unlimited availability, blazingly fast performance, and support are the new standard.

High expectations, together with the decomposition into microservices, made providing an excellent API even more complicated.

Too often, I see enterprises failing to provide consistent APIs, startups not having the time and resources to build their APIs with love, and API consumers creating their own façade over complex APIs they have to use.


Image for post
Image for post

Use Change Management instead of API Versioning.

Over and over we see HTTP APIs (and now GraphQL APIs) fall into the same versioning trap. Semantic versioning isn’t meant for distributed systems where the goal is to have many components evolving independently. In other words — when was the last time you’ve seen Twitter or Google version number in your browser’s URL?

API providers are trying to fit a square peg into a round hole. They are abusing resource identifiers (or GraphQL type names) to carry information about the version of the particular resource. It’s like having your age in your…


Image for post
Image for post

You want a grain, but you need to buy the whole silo. Every API provider today is forcing you to get the whole package. But what if you just want to send that one payment, put that one file into version control or just one query of the weather in the paradise you are going to visit next week?

I’m sorry, you can’t. Register here. Get that authentication token. Pay there. Learn new paradigms and vocabularies. Create a new user identity. Similar data but not really. It’s way faster to go to your browser, authenticate on your bank’s website (you’ve…

Zdenek “Z” Nemec

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store