The idea for this post came when I saw Kong’s announcement of new design and testing tool Kong Studio.

The words we use in our vocabulary shape our thinking and direction of thoughts. If we use technical terms even if it is not necessary, we push away the non-technical people and enforce the specific role of technical people in the domain. API Design is one of these domains. It has been dominated by technical language and required technical skills and specification (pedantic way) understanding. I mean to be able to make any API design you must have had ability to write code-ish machine-readable text files. Great API products are not build with that kind of approach and thinking. That is techno-centric (see below).

Regardless what the term (below) is used, they all have grounds in specification which according to Merriam-Webster is “a detailed precise presentation of something or of a plan or proposal for something —usually used in plural” or “a statement of legal particulars (as of charges or of contract terms) also : a single item of such statement

OpenAPI spec(ification) is defined as “The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.


To me this term is too technical. Users of it want to emphasize the technical nature or APIs. To me this term is a tool to maintain hegemony of technical people in APIs. Great APIs are created with multidisciplinarry teams. In those cases common language and understanding is hardly achieved efficiently with technical language. At the purist form of this is to work on for example with OpenAPI spec text (YAML, JSON) only and expect business people, marketing, architects, security experts and support to understand what the hell are we building. That will fail.

The tools build around the spec driven approach with some visual elements have emerged lately like mushrooms in the forest after the summer. You can find them under every tree and bush. Their shape and colors differ, but they are still mushrooms. These tools take at least one step forward from pure text formatting only.


As long as we do what the contract says we are cool. Right! The content can be what ever but it’s a contract we agree. This approach does not implicitly include the usability which is fundamental element of great APIs and DX. It might have all the needed functions, endpoints and parameters and it follows the “contract” but that’s it. In case of API family, the APIs might differ in naming patterns, error handling and the common elements often required to be unified. Still the contracts are valid. I know I’m cutting corners, but hey this is opinionated blog series.

This approach at least contains the notion of customer as the contract is expected to have two parties: the consumer and API provider. This is one step forward again in Developer eXperience thinking. To me this approach has too much product focus.

Remember the initial Developer eXperience maturity model introduced in #67 - Developer eXperience maturity model


By default design is about user experience and maximising it. The customer is in the focus, not the contractual nature or technical presentation of the API. This is the notion I like in the term and thus I use it instead of the above. According to Shackel (2009)Good system design depends upon solving the dynamic interacting needs of the four principal components of any user–systemsituation: user, task, tool and environment.” This statement includes the user as one of the core elements. Without focusing design-wise to match the user’s needs and expectation, you are likely focus on wrong things and waste your time.

Norman (1988) defined user-centered design as “a philosophy based on the needs and interests of the user, with an emphasis on making products usable and understandable

Design-first at best uses the spec, but that is not visible unless absolutely necessary. Designer has tools to visually and automatically get the features included in the API design. The idea is not to focus on technical presenation of the API, but usability and feeling (loveability), make it feel natural and enjoyable to use. The focus is on the consuming developer, not the product or technology, or for fuck sake definitely not nitpicking with the specification format.

To build great APIs you need the “whole village”, all the aspects to handle a product, marketing, sales, support and all. You need to have common understanding of what you are about to build from day one. Your tools should be usable and understandable by all the team members to maximise output from the team. You should never forget who you are serving - the developer.

Some more to read from 100 Days DX