Global
There are five key API design principles. Here I will elaborate on each of these areas:
Documentation
Documentation is a key principle of API design and development. Please keep in mind that the developers are the users of your API; therefore, the documentation should be the paramount deliverable item of APIs. They need to be detailed in every aspect whether you call it a contract definition or developer guide, it needs to be easy to understand and simple to use. Keep it up-to-date and eliminate outdated items. There are tools available such as Swagger that simplify the complexities and techniques involved in document writing.
Content Negotiation
There should be a provision for flexibility in terms of technology and usage preferences, which allows developers to prefer an option that best suits them. Greater flexibility helps in accelerating the adaption of your APIs. It includes:
- Supporting multiple formats (media types)
- Understanding developers’ technological preferences, and support if possible
- Adapting the preferred standards and specifications
Compatibility
It is important to be compatible with each consumer and changing business needs. It is also essential to version each API release and document each changelog, so that the behavior of the API remains consistent, thus keeping the various consumers unaffected and stable. Do not forget to deprecate the older and unused versions.
Adaptability
The APIs that are published must be easy to understand and simple to use. There should be a provision for developers to try-out your APIs before they see benefits and start adopting them for production use. This should help to ease onboarding of third party developers and partners. As the saying goes, “The first impression is the last impression”, and hence chances are high that developers will adopt your APIs if they find them easy to implement. A community for trial-users and enterprise support for production-users will greatly enhance the adoption of APIs.
Security
This must be the most basic principle of any application design and development. Moreover, when securing the public APIs, the complexity grows in terms of design factors. Some of the key factors to consider are:
- Always use SSL for public APIs
- Use tried and tested authentication schemes
- Enable only authorized access to each resource
- Always encrypt key information that is shared over the wire
API Guidelines and Best Practices
Some of the guidelines and best practices described below are subjective but they are essential in today’s API development. They provide fundamental benefits and help to stay at par with industry wide adoption of best practices:
Vocabulary
This refers to the standard naming conventions one should following while naming each API endpoint. They should be human readable, easy to understand, and follow the HTTP standards.
Versioning
By versioning, you are allowing various consumers to access your published APIs in two different variations. Though Version management adds complexity to the existing APIs, they do however help in better management of API endpoints, thereby serving various consumers through different mediums. There are two different ways to implement this:
- URL – For e.g., api.myorg.com/v1/users
- Accept Header – requesting for specific version via request/accept header
Support Multiple Media Types
At any point in time, a given object or resource can have multiple representations. This is necessary so that various consumers can request the content or resource in the manner that they would like. Having said that, it is not necessary to support all media types, only the ones that are required based on specific use cases.
Here is an example of support for two different data formats:
Caching and Concurrency Control
Caching improves performance, thereby providing faster access to frequently accessed resources and eliminating the load on backend services. However, with caching comes the challenge of managing concurrent access. Therefore, it is essential to manage the caching in a better way using HTTP standards such as:
- ETag – Entity tagging. Equivalent to versioning each entity for updates
- Last-Modified – Contains the last modified timestamp
Standard Response Codes
This responsibility lies with business owners as it affects the business needs of consumers of your APIs. The contract definition should contain all possible error codes that could occur with each API.
- Adhere to the standard HTTP response codes
- Include both business and developer messages. Developer messages should be optional, and contain technical messages that guide debugging and troubleshooting techniques.
- Due to security reasons, do not reveal too much about the request (to avoid Cross-Site Request Forgery).
- Best practice is to limit the list of potential error codes, as too many error codes leads to chaos.
Security Considerations
This does not require much explanation, as security requirements are the basic needs of any application or an API. Keep in mind that your API’s are mostly public, so invest the effort required to secure them. API management platforms (explained in the later section) provides security mechanisms; however, as an API developer, you should be aware of the current trends and industry best practices adopted in addressing security requirements.
- Always use SSL
- APIs are stateless, so avoid session/cookie management – authenticate each request
- Authorize based on resource, not on URL
- HTTP status code 401 vs. 403: Some may prefer to use code 401 rather than 403 to indicate that either authentication or authorization failed
- Follow the guidelines defined by Open Web Application Security Project (OWASP) Threat Protection
Possible Authentication Schemes:
| Basic Authentication | • Must be on SSL only
• Encoded using Base64 and sent in Authorization request header • Ideal to use within secured networks |
| SAML | • Transport agnostic, can be used with HTTP, SOAP or JMS
• Ideal for B2B enterprise applications |
| OAuth | • Uses only HTTP
• Ideal for consumer facing applications that authorize data for 3rd party access • OAuth 2.0 with bearer tokens is ideal for mobile applications |
| JSON Web Token (JWT) | • Compact, transmission is fast
• Can be sent through URL query parameter, POST parameter or inside HTTP header |
Great! We now have the strategy in place, understand the design principles and best practices necessary for the development of APIs. In my next blog I will help you to understand the capabilities of API management platforms that address the non-functional challenges, changing business demands, and ways to accelerate the development and adaptation of APIs.
This is the second blog in a 3-part series on API. “Part 1: API Centric Design” can be viewed here. “Part 3: Understanding the Capabilities of API Management Platforms can be viewed here.
