Yesterday after the post (Purpose of API Evaluation Framework) it kind became clear to me. We do not discuss the role of API designer too much but instead focus on technical details often listed in API Design Guide. And that is at best. Often the discussion does not even go that far.

API Designers are rare?

My assumption is that developers implementing the APIS act as designers too. In smaller companies this is probably question of resources. You can’t afford a dedicated API Designer and thus you are forced to let some of the API developers to act as designers. In most cases that does not necessarily result to best results. Your API developers (implementing it) are most likely looking at the solution from internal point of view. It requires specific mindset to be able to cooperate and adjust the solution to customer’s needs. Some developers can become great API designers and great API designers often have engineering background.

Team work with clear ownership

Of course the whole team has to be involved in designing the API, but if the design is “owned by the team” is easily is not owned by anyone. Someone has to take ownership of the design. Especially if there’s plenty of APIs. In those cases the developer implementing some specific API does not have often time or even interest to make sure that desing is inline with rest of the APIs and result is consistent. Often the hardcore developers don’t have time to do the sometimes time consuming evaluation of the API design with customers. With ownership I don’t mean dictatorship. The one leadiing API designs should be wise enough to listen to viewpoints coming from other team members.

Work done with more traditional APIs

In the realm of the traditional software or framework APIs (not used over http but locally) Stylos and Meyers have mapped the space of API decisions (2007). According to them when creating new application programming interfaces (APIs), designers must make many decisions. These decisions affect the quality of the resulting APIs in terms of:

The article mentioned above contains an overview of API design decisions relevant to object-oriented languages.

Space of API Design Decisions for web APIs

I was not able to find such mapping for web APIs. Looking at the above illustration of API design decisions relevant to object-oriented languages, it’s easy top see that for example API Design Guide answers often to Design Patterns part. Naming patterns are also quite often in API Design Guides. Method selection is not often directly defined in API Design Guides. There’s often guide lines that organisation uses this and that methods (GET/POST/PUT/PATCH/DELETE) but not that all endpoints should have all the methods. It’s obvious that API Design Guides are not that picky or provide clear instructions for all the situations a API Designer is faced with.

The spot that really intrigues me is marked in the picture below with dotted lines. That is the sweetspot of API Design. Helping the designer to perform better is what I’m after. To be able to offer tools and frameworks we first must understand their daily life. Just like with API consumers, to be able to offer them best possible DX, we need to know them thoroughly. I would love to see some more research around the API designer’s work. The reason why I’m so into this subject is that we are hiring API Designer and he/she will be in my team. I want to support all my team members with all the possible means I have.

Some decisions have greater consequences

Not all decisions are as “important”. Some decisions have greater consequences than others. Here’s a few guide lines for evaluating the severity of decision.

Design frequency How often this decision comes up when designing APIs. For example, an API designer might frequently have to make naming decisions and only rarely have to decide which asynchronous execution pattern to provide.

Design difficulty How likely API designers are to make the decision sub-optimally.

Use frequency How often API users are directly affected by a decision.

Use difficulty How costly a sub-optimal decision is for an API user.

I would be tempted to discover this topic a bit further, but now I don’t have the energy. I just had my lungs X-Rayed and I’m waiting for the results. Most likely I have pneumonia.

Some more to read from 100 Days DX