What Is API Design?
API design is a process of developing APIs and creating an interface that can allow users and customers access data and application features.
Since API consumers are machines and API users are developers, many of API design’s elements are technical, as well as visual. They’re reflected in API structure and documentation.
What Makes a Good API Design?
Here’s what to know when designing an API.
- Simplicity. A simple API uses widely accepted formats, data structures and methods. Easy to achieve with REST APIs, for example, as they support JSON requests.
- Flexibility. With many companies branching out into different use cases like IoT, your APIs must be consumer-agnostic to meet the evolving market needs.
- Security. OAuth 2.0 is a secure method of authorisation, so your API (unless it’s open-ended) should include that, along with SSL certification.
To design a good API, you need to keep your goal and audience in mind. They are experienced developers familiar with API architecture like REST and functions like CRUD. So, a well-designed API would often be based on them.
Is API Design Easy?
No. You see many architectures with inconsistent structure and documentation. That’s a testament to how challenging API design is, but it doesn’t mean that it’s not important.
I’ll now explain what makes a great API and why API design is a must for your organisation.
What Makes a Great API?
Every API needs several elements to function. They are:
- API documentation
- Software interface
- Authentication and authorisation
As I stated above, the simplicity and flexibility principles are essential to designing great APIs. Let’s explore them.
Simple API Design
Simple API design is about data structures, method structures, and authentication. For instance, the commonly used REST APIs are simple because they support the widely accepted JSON format and use HTTP to communicate the methods.
Flexible API Design
With APIs that give developers control and offer options like webhooks, all API consumers (in this case, machines) need to do is to conform to the API contract. Such flexible APIs allow consumers to interact in accordance with that contract.
Such interactions allow to achieve the desired output, irrespective of what the consumer is - a web app, a Linux server, or a mobile app. And users therefore have a wider range of API use cases. That’s why it’s important to your customers that you deliver flexible APIs.
E.g, if you have a mainframe for delivering APIs to your clients and it costs you a lot of money to maintain, you can rebuild your app on a Linux server, and a flexible API would allow you to provide web services with lower costs and no change in UX.
API Documentation
If a developer can’t figure out from API documentation what your API can do for them and how, they’ll just go for another API.
However, if API documentation is concise, easily navigated and offers real-life examples, your users won’t have to waste time trying to figure it out. That’s why this API design element is important.
Here’s an example of Mailchimp’s API documentation. Note how their OpenCommerce API documentation is structured by functions, with little unnecessary info.
Why Is API Design Important?
A well-designed API most importantly ensures excellent UX. And, since users are mostly developers, technical sophistication is a must. Today, that’s commonly achieved by standardised API design.
Such designs can help your organisation save time and money on development, and your customers on implementation.
Standardised design APIs are flexible and simple. In addition to what I already mentioned, API design enhances sustainability of your offerings. E.g., if you have a new team in place, they can use a standardised framework familiar to your clients to develop new APIs rather than start from scratch.
API Design Guidelines
API design is done according to API design guidelines. They’re an example of standardised designs I mentioned. Some leaders like Microsoft have their own guidelines for their APIs. They include REST API best practices that most developers follow. If you follow them too, your customers will have an easier time with your APIs.
Types of API
Picking the right API type is crucial for its intended function. Here are the most common types of API architectures.
- REST APIs are, as I mentioned, the most common APIs today. They’re used to transfer data via HTTP from server to client. You can peruse Mark Masse’s REST API design rulebook for further info.
- SOAP APIs are used to transmit data across networks. Unlike REST APIs that use JSON, SOAP uses XML. SOAP is heavier than REST and is therefore less common.
- RPC APIs are used to execute scripts on a server and are popular in remote networks. They can use both JSON and XML but have more limited capabilities than REST or SOAP.
How to Design a Great API?
APIs are tech products, so the technologies used in building and validating APIs are vital to the design. REST APIs are simple in that respect as they all incorporate JSON and some authorisation (OAuth or otherwise). An SSL certificate is also a must, to ensure security.
Regarding API design tech tools, Linx for building and Postman for validating/testing is a popular combination for REST API design. For documentation, Swagger editor is the leader.
Choice of API architecture is also pivotal. Whilst REST API design might be popular, it might not be best for you, depending on your use case. As I mentioned, SOAP and RPC APIs can meet different needs.
For instance, SOAP could be an option for users that need to integrate their resources into other systems. And RPC, especially as part of gRPC framework, can add value for companies that require several data centres to be connected.
So, you should keep your goals and audience in mind when choosing API design type.
API Design Team
If you monetise APIs, the industry know-how and tech skills of the API design team are a a must.
An ideal team would include a leader serving as product manager, who sets clear goals focusing on the end user’s needs. They should be central to the team’s vision, and the team needs to understand the API’s potential for business.
The team can include engineers, API designers familiar with the best design approaches, InfoSec specialists, and operational staff (account managers) that would run the APIs and user support. Over time, the team can grow.
Why Tailor API Design Towards End User?
A tech product is only as good as its UX, and APIs are no exception. Basically, if your API design isn’t usable by its audience, that audience isn’t going to buy it. That’s why API design must be tailored towards its end user.
Purposes of Designing an API
If an API is a product, the API design goal needs to stem from your business goals. And those will depend on your strategy and the problems that your product solves. Therefore, ensure that the goals set when designing an API align with your strategy.
For example, are you looking to unlock more revenue streams and therefore joining the API market to test the waters?
If so, the API design team should have that goal in mind and ensure that new customers want to buy your product, and your existing SaaS customers want to switch to it. This can be done by:
- Making APIs’ functions as clear as possible in documentation
- Applying consistent formatting across all documentation (lowercase letters, HTTP methods, standard URLs conventions, etc).
- Testing and validating your APIs - internally and by test users. Today, rewards-based programs are popular across most markets, so you can hire test users by offering some bonuses, like discounts or free trials for some products.
Or you may be looking to increase your retention levels by developing better products. In this case, you can:
- Review your existing APIs to see what can be improved, and collect feedback. Use it as guidelines for future API design. If a client has new software, offer relevant use case examples for your API in documentation.
- Add integrations. Today, many companies develop their own products in-house due to digital transformation that you can also capitalise on. E.g. if a warehousing company develops sorting software and your APIs offer some compatible add-ons, such integration would set you apart.
Digital transformation offers many opportunities for API developers. APIs that can be integrated with major software, especially IoT, would have an edge over the rest.
Benefits of Good API Design
Here’s an overview of the main API design benefits discussed:
Business API Design Benefits
- Increased target audience thanks to digital transformation
- Stronger brand recognition
- Better UX that converts to high retention levels
Technology API Design Benefits
- Consistent and standardised design = saving time and money with future products
- Improved scalability and sustainability of APIs and API-based products
- Easier integration into new and existing software products
- More opportunities for collaboration with other providers
What Makes an API Valuable?
These are factors that make APIs valuable to your business, as confirmed by McKinsey:
- Diverse innovation and monetisation opportunities thanks to increased market presence
- Opportunities to break into new markets and capitalise on digital transformation
- Team growth and development - new resources can be utilised across many projects.
Of course, every business would benefit from APIs differently. It’s up to you as industry and team leaders to define the APIs’ value for yourselves.
I provided some examples above, but digital transformation means we have new offerings every day. Use the customer feedback you get for them to define the API value for YOUR business.
API As a Product
Treating your API as a SaaS product rather than middleware requires lifecycle management. Planning, design and release are just the first phase. Listening to feedback and implementing it, testing and maintenance, marketing and user engagement - those are just a few requirements for productising your API.
The most important thing is to always keep in mind how your products can help your clients. And that’s about much more than just selling them.
What Are API Programs
Introducing an initiative called API program is a strategy for productising your new or existing APIs. It works similar to project-based models. They’d allow different members of your organisation, like project managers, salespersons, engineers and even API evangelists, to work on an API product together as a project.
Developer Experience
As APIs are developers’ products, designing them involves balancing UX and Developer Experience (DX). As the main users, they’re your best source of feedback and improvements. So, DX is crucial in your design. The KPI here is TTFHW (“Time to First Hello World”) - the less time it takes for a developer to make an MVP with your API, the better your design is.
Final Thoughts
I covered the concept of API design, why it’s important for organisations who sell APIs as products, and the best practices that help derive the most value.
API design is a process of making your API product the best it can be. Often, the simpler and more flexible it is, the more value it adds for your customers - although that depends on your use cases. Make sure to keep these principles and practices in mind and apply them within your team!
