How to design an API

A quick, theoretical guide

Photo by Med Badr Chemmaoui on Unsplash

Hello everyone, as a Back-end engineer, my main task is to develop APIs. This is a daily task, and I am increasingly looking to produce higher-quality products. Hence, we decided to collaborate with the Brands team in Cornershop by Uber to have a guide on designing an API that has factual information and is easy to consult.

So I started my research and found an excellent article that helped me with this purpose.

In this post, I summarize the article cited below and share a condensed version of the information needed to create an initial design document of an API. I’ve outlined it below with key callouts and relevant questions in each section.

An effective API design should be based on its overall corporate strategy and contribute to its objectives. You know you have good strategy elements when you can answer the following three questions clearly:

1. Why do we want to implement APIs?
2. What are the results we are looking to achieve with these APIs?
3. How will the API be executed to achieve the desired results?

⁉️ The reason

• What is the value of the API?
• Do you have a business objective in mind? If so, what is it? Are you looking to increase earnings, explore new business models, improve time-to-market or develop new distribution channels?
• Do you have a tech objective in mind? If so, what is it? Do you want to improve mobile and app integration or allow for greater device connectivity?

🎯 The target

• What are the results we want to achieve with these APIs?
• What do APIs actually do and how do they influence the overall business strategy?

⚙️ The method

• What technology is used to design the APIs?
• How are APIs designed?
• How are APIs maintained?
• How are they promoted within the company or marketed to the outside world?
• What are the available resources?
• Who should be part of the team?
• How do we measure success against the business objectives that were set?

🧑🏼‍💻 The initial team

The following is a list of profiles or people that you should consider to create your work team.

• A product-focused person who is responsible for strategy and objectives
• Design-focused team members to ensure the use of API design best practices
• Engineers to implement API technology
• Members of the operations team executing it

Cornershop’s time: For example, in my team & the brands team, we have Valoche who defines the product, Seba who ensures good practices in the group and I developing the APIs

🔍 How to find and describe the API value?

The process

1. Describe the work requested by the users
2. Identify specific challenges faced by users before, during, and after
3. Summarize the potential benefits to the user
4. Write several statements that explain, in detail, the communication between the API and the user profile.

How to define the value of your API program?

1. Who is the user?
2. Are they current customers, partners, external developers?
3. What are their roles — are they data scientists or mobile technology developers?
4. What are the requirements or preferences?
5. What are the users’ weaknesses that we help mitigate or the benefits we can offer them?
6. What are the case studies supported by your API?
7. How can user value be increased over time? What are the essential milestones concerning internal or external changes?
8. What value is generated for your company internally?

🎨 User-driven design and implementation

Basic principles

• Simplicity: Data format, method structure, data model, authentication, usage policies.
• Flexibility: What is the potential operating space based on?

Questions to keep in mind

To carefully analyze your API design, consider the following five questions:

1. Did we design the API to support our case studies?
2. Are we implementing RESTful APIs just because?
3. Did we set out our data model without considering the case studies?
4. Which geographical regions are the most important and have we planned our data centers accordingly?
5. Did we synchronize the API design with the rest of our products?

📄 Recommendations

During his keynote address at the 2012 O’Reilly Open Source Convention, John Musser highlighted the 5 keys for a suitable API:

1. Provide a valuable service
2. Have a plan and a business model
3. Allow it to be simple, flexible and easy to adopt
4. Enable its management and measurement
5. Provide support to developers

References

• What does API design consist of? https://www.redhat.com/es/topics/api/what-is-api-design
• What Makes a Great Open API? https://www.slideshare.net/jmusser/what-makes-a-great-open-api