blog posts

What is APIs design?

APIs design refers to the process of developing application programming interfaces (APIs). That expose data and application functionality for use by developers and users. In addition APIs are important to modern organizations, adding new capabilities to everything from their operations and products to their partnership strategies. It’s no longer a stretch to say that most organizations don’t ask whether to engage in API programs. But how to do so.

An effective API program has to build on an organization’s overarching corporate strategy and contribute to its objectives. You’ll know you have the makings of a great strategy when you can answer the following 3 questions in a clear way:

• Why do we want to implement APIs?
• What concrete outcomes do we want to achieve with these APIs?
• How do we plan to execute the API program to achieve that?

Why do we want to implement APIs?

People often misinterpret this question in different ways. Firstly, rather than focus on the value of the API, it’s helpful to think of the value of the effect of the API. Remember, it’s the organization’s core business that’s valuable, not necessarily the API. An API is valuable when it becomes a channel that provides new types of access to the existing value an organization delivers.

Another common misconception is believing that for an API to be valuable users must be prepared to pay for it. This is true only if the API itself is the product. In most models, this is not the case. APIs are usually driving some other metric—sales, affiliate referrals, brand awareness, etc. The value of the API to users is the result of an API call (service request and response), rather than the call itself.

What concrete outcomes do we want to achieve with these APIs?

The second question should be “What concrete outcomes do we want to achieve with these APIs?” In other words, “What do the APIs actually do and what impact do they have on the wider business strategy?”

Both the concepts of the internal view and the external view of an organization can help to define the what of the API. The internal view refers to specific, valuable assets an organization possesses. The more valuable and unique the services and resources offered the more suitable they are for an API program.

An organization that has unique data could take advantage of this resource by allowing access to the data via API. Unique content, data, and services can make access to the API extremely valuable.

When deciding what an API should do for a business, both internal and external views
need to be examine. The decision about the what is then usually a combination of the 2 views.

In concrete terms, while the why is unlikely to change often, the what may vary significantly based on external factors—such as markets, technical considerations, or economic conditions. Internal directions about the value of an asset may change, which could also affect what should be achieved with an API.

How do we plan to execute the API program to achieve that?

Therefore The final question, “How do we design our API program to achieve what we want?” is all about implementation and execution.

So Teams must ask themselves:

• What technology is use to build the APIs?
• How are the APIs design?
•  And How are the APIs maintained?
• How are the APIs promoted inside the organization or marketed to the outside world?
• What resources are available?
• Who should be on the team?
• How do we track success against the business goals that have been set?

The API team

An API team is most closely related to a “product” team—whether your customers are internal or external, you are in charge of building, deploying, operating, and optimizing the infrastructure others depend on.

Just like product teams, API teams can also be very diverse, but typically they should include a product-centric person who acts as the keeper of strategy and goals, design-focused team members who ensure best practice in API design, engineers who put the API technology in place, and operations team members who will run the API.

Over time you may also have additional people involved, including support and community team members, API evangelists, security representatives, and others.

Design and implement with the user in mind

Good API design has some core principles, which may differ in implementation. Here’s an analogy: every car has a steering wheel, brake pedals, and an accelerator. You might find that the hazard lights, the trunk release, or radio are slightly different from model to model, but it’s rare that an experienced driver can’t figure out how to drive a rental car.

This level of “ready-to-drive” design is what great API teams strive for—APIs which require little or no explanation for the experienced practitioner to begin using them.

Simplicity

Simplicity of API design depends on the context. A particular design may be simple for one use case but very complex for another, so the granularity of API methods must be balanced. So It can be useful to think about simplicity on several levels, including:

• Data format. Support of XML, JSON, proprietary formats, or a combination.
• Method structure. Methods can be very generic, returning a broad set of data, or very specific to allow for targeted requests. Methods are also usually called in a certain sequence to achieve certain use cases.
• Data model. The underlying data model can be very similar or very different to what is actually expose via the API. This has an impact on usability, as well as maintainability.
• Authentication. Different authentication mechanisms have different strengths and weaknesses. The most suitable one depends on the context.
• Usage policies. Rights and quotas for developers should be easy to understand and work with.

Flexibility

Making an API simple may conflict with making it flexible. An API created with only simplicity in mind runs the risk of becoming overly tailored, serving only very specific use cases, and  So may not be flexible enough for other use cases.

To establish flexibility, first find out what the potential space of operations is based on, including the underlying systems and data models, and defining what subset of these operations is feasible and valuable. In order to find the right balance between simplicity and flexibility:

• Try to expose atomic operations. By combining atomic operations, the full space can be cover.
• Identify the most common and valuable use cases. Design a second layer of meta operations that combine several atomic operations to serve these use cases.

Critical questions for consideration

In order to think through your API design, consider the following  questions:

1. Have we designed the API to support our use cases? The next step after identifying the main use cases is to design the API so that it supports these use cases. Flexibility is important so as not to exclude any use cases that may be less frequent, but should still be supported to allow for innovation.
2. Are we being RESTful for the sake of it? RESTful APIs are quite fashionable, but you shouldn’t follow this trend just for the sake of fashion. There are use cases which are very well suited for it, but there are others that favor other architectural styles, such as GraphQL.
3. Did we expose our data model without thinking about use cases? An API should be supported by a layer that abstracts from your actual data model. As a general rule, don’t have an API that goes directly to your database—although there may be cases which require that.
4. Which geographic regions are most important and have we planned our datacenters accordingly? API design must also cover nonfunctional elements, such as latency and availability. Make sure to choose datacenters that are geographically close to where you have most of your users.
5. Are we synchronizing the API design with our other products? If the API is not the sole product of your business, make sure that the API design is coordinated with the design of the other products. It may be that you decide to completely decouple API design from other products. Even if this is the case, plans to decouple API design from other products needs to be made clear and communicated both internally and externally.