Thread by @getpostman

8 traits of an effective #APIFirst design 🛠️✏️

Thread 🧵

(via @apihandyman 😎)

Before we get started, let's cover the basics.

✔️What is API-First?
✔️ What is API-First Design?

API-first is an organizational strategy and development model in which APIs are prioritized to deliver maximum value to the business. In this model, applications are designed and built by composing private, partner, or public APIs. postman.com/api-first/

API-first design can improve the quality of an API’s interface contract in a way that positively contributes to the API-first strategy.

To achieve an API-First design, let's dive into the following traits 👇

🪐Alignment with an organization’s goals

An API design is a representation of the API’s purpose, and an API whose purpose is not aligned with the organization’s goals will not contribute directly or indirectly to its business.

Such APIs are a waste of time and money, and will often be hard to use and reuse, if they are used at all.

🪐 Reusability

An API whose purpose is aligned with the organization’s goals is more likely to be reused, but there’s still a risk that its design will be so tailored to its first consumer that no one will be able to reuse it.

At best, a non-reusable design leads to more work to fix the design, the implementation, and the code of the existing consumer(s). At worst, it leads to the creation of a 2nd API—or even more APIs. All of these outcomes increase development costs and lengthen the delivery time.

🪐 Interoperability

API-first design enables teams across the organization to re-use APIs and leads to the creation of solutions that rely on more than one.

Leveraging data and formats that are at least locally interoperable and standardized will reduce error risks while simplifying and accelerating consumer developments.

🪐 The ability to evolve

API-first design involves making the right decisions during an API’s initial design and further evolutions, which makes it easier for teams to modify the API and to integrate new features without introducing non-backward-compatible changes.

Such changes, which are also called breaking changes, require existing consumers to update their code to use the modified API, which increases development costs and time. They can also cause people to be reluctant to introduce changes and slow down the organization’s plan.

🪐 User-friendliness

The experience of the developers who are working on an application that consumes an API, as well as the experience of its end users, will impact the value an API can generate.

API-first design helps create a good developer experience, also called DX, by making the API easy to understand and use by anyone—especially non-experts in its domain.

It also helps prevent consumers from having to write complex code to use it, and possibly proposes solutions to solve limitations. These benefits speed up development and make the API more appealing.

Happy and more efficient end users will generate more value, and you can support their happiness and efficiency in many ways. For instance, you should avoid providing insufficient error feedback that will not help them solve an issue.

🪐 Security

API security is a core concern for any API across its whole lifecycle. Still, it’s even more important for APIs that are designed and developed according to the API-first strategy, as these APIs can be reused in various contexts inside and outside the organization.

An API-first design can secure an API by specifying each feature’s data, how it is represented in the interface contract, and how accesses can be segmented. Each aspect must be carefully considered to ensure that nothing sensitive is unduly exposed.

🪐 Efficiency

API performance is not only an implementation concern; some design decisions may affect the performance of an API, as well.

Choosing the wrong data or operation granularity can not only lead to a very poor DX, but may also lead to many API calls and unnecessary processing, which increases the amount of resources needed to operate an API. This could cause performance issues or high provider costs.

🪐 Pragmatism

The ideal API design can be difficult to implement, often because of pre-existing design, implementation, or architecture limitations.

It’s the API’s job to hide inner complexity, but this can lead to excessively high development or running costs, as well as longer time to delivery. In such a situation, a less-than-ideal design may be a better option, either temporarily or definitely.

That's all for now! 👋🚀

Read the full blog from @apihandyman here: blog.postman.com/api-first-desi…