In this post, we’re taking a look at general API design best practices for your enterprise, as well as some specific to RESTful API design.
APIs, or application programming interface, are a key tool for accelerating digital transformation. It’s no wonder then that they’re now widely adopted across all industries. If software is eating the world, then APIs are eating software.
APIs simplify adding new functionalities to existing software. These functions unlock new business opportunities for increased profits and brand satisfaction. Because many developers (and other users in your enterprise and ecosystem) may work with an API over time, it’s important to keep API design best practices in mind.
61% of organizations used more APIs in 2020 vs. 2019, and 71% planned to use more in 2021. The reason for API popularity is because APIs, when they’re done right, are the flashpoint where tech meets business goals.
The Benefits of Good API Design
The reality for large organizations is that API design impacts roles across business and IT, not just developers. Collaboration is key. This helps drive adoption, reuse and ensures APIs are aligned to business needs.
With the rise of APIs, it’s critical that those roles involved in creating them link best API design practices to the benefits of good API design. Well-designed APIs create a better user experience for consumers of the functionality – both internally and across your ecosystem.
A REST API (also known as RESTful API) is an API or web API based on the REST architectural style. You’re likely designing REST APIs (most commonly aligning to OpenAPI Specification (OAS) 2.0, 3.0 or 3.1) to expose existing business functions as reusable digital building blocks.
Even though there are different types of APIs for different applications and use cases (think SOAP services, events-based etc.), all well-designed APIs share some common characteristics, and a good solution allows you to support them all. In this post we’ll be looking at some of the common design principles, along with those more focused to RESTful APIs.
A good API is easy to work with and read. Developers working with the API over time appreciate it if they can quickly memorize resources and operations. Business and product stakeholders should be able to easily understand what the API does, and what capability or function it is supporting.
APIs should be built with future utility in mind. Designers and developers build on existing APIs over time. An API created with best practices in API design is a robust foundation for future additions. This makes it possible for future iterations, and ensures your APIs are best-of-breed to deliver business results via use in digital products and services.
General API Design Best Practices
These best practices are common across your API strategy as a whole, regardless of the type of API you’re creating. To maximize initial adoption rates, it’s much easier to follow these best practices from the start.
1. Create business and technical views of the design
Both business and technical users will need to interact with the API design. You want views that are easily understood by both. API abstraction can help here.
2. Design using an Information Model
Using a centralized information model containing resources and model objects to design the payloads for the APIs helps ensure data structures are consistent. This improves the consuming developer’s experience and ensures your APIs are consistent.
3. Align to Business Capability Model(s)
Classifying APIs to encapsulate business functions organizes them as strategic business assets. This helps you better understand existing coverage, and prevent API duplication. Using a holistic catalog where all assets are aligned to business capability model(s) helps drive API discovery.
4. Document Relationships Between APIs Upfront
Capturing the lineage between provider and consumers in the API design from the beginning can help with executing changes over time. This helps avoid any breaking changes and ensures a good experience for people using the API.
5. Capture API Complexity from the Beginning
API providers may overlook certain technical details like SLAs (service level agreements) and NFRs (non-functional requirements) at the initial stages. Consider all requirements before the API is deployed, when they are easier to manage.
6. Validate Against Governance and Standards Rules
Good APIs are complete, consistent, and compliant when checked against your enterprise’s governance model. Products like ignite save hours of time by automating these checks and remediating violations without manual edits.
7. Create Clear Documentation
The faster a developer can understand the structure of the API, the faster they will use it. Good documentation creates a better developer experience. Consuming developers can easily get an overall sense of how they can quickly integrate the API into their application.
Similarly, poor or incomplete documentation is a major turn-off. Tools that generate documentation automatically like ignite help keep team productivity high.
REST API Design Best Practices
These are some of the common design best practices specific to designing RESTful APIs. We’ll be running through some SOAP and Event-based design principles in upcoming posts – be sure to subscribe to the blog in the sidebar of this post for those!
1. Build In Security
Be familiar with all the security standards that are relevant to your API. This starts with an HTTP Strict Transport Security (HSTS) policy. Data security is a hot topic, and your API should include all security measures to protect sensitive data without sacrificing functionality.
Select the appropriate security policies for your API’s use case (e.g. OAuth, API keys), on top of HSTS to secure your data.
2. Use SSL/TLS
Always use SSL/TLS to encrypt communication with your API. This should be a baseline standard.
3. REST API Should Accept and Respond with JSON
JSON is a standardized open format for transferring data. The standard is for RESTful APIs to accept and respond to JSON requests.
4. Tame Data With Filtering, Sorting, and Pagination
Some databases can be so large that trying to return it all at once slows or crashes the system. Filtering items is one solution to avoid this.
Paginating data also allows you to return a few results at a time. This also avoids lagtime caused by trying to load all the data at once.
By reducing the drain on server resources, filtering and pagination improve API performance. For large databases or those expected to grow, these features are important to plan for in the API design.
5. Limit Resource Nesting Levels
Resource objectives are interlinked or have some kind of hierarchy with each other. Developers sometimes reflect this by nesting resources. However, too many nested levels can add complexity that becomes cumbersome.
When nesting resources, it’s best to limit them to one level with REST API.
6. Use Nouns in URLs
RESTful URI should refer to nouns instead of verbs. This is because nouns can be described differently than verbs. When you use nouns, you can describe resources functionality using attributes. Attributes examples include system users, accounts, other devices on the network.
7. Name Collections With Plural Nouns
Use plural nouns when developing a collection in REST API. This makes more sense to other developers reading the code. A collection of things is by fault plural. You communicate that you are referring to more than one from the start when you use plural nouns. No one has to open the collection to verify what it is.
8. Include Error Status Codes
Status codes are helpful for developers to identify an issue quickly. Knowing what to fix reduces the time spent writing parsers to address errors. HTTP has over 100 status codes, from locating a missing resource to uncovering the reason for a denied session. This helps developers create routines for managing specific errors signaled by status codes.
Moving Forward With APIs
API use is increasing across industries, including technology, financial services, manufacturing. Well-designed APIs are key to delivering the promises of an API First approach.
One fundamental shift businesses must make is to not think APIs are only an IT responsibility. The API business strategy should reflect that the API is an interface between products and customers. Customers should be at the center of the API design. The API business strategy needs to have a way to incorporate consumer feedback.
We are here to help companies structure their thinking around their API business strategy. Download your free Forrester report API Product Management is Key for API Success for more tactics on how to move to a business-led API program.
