Guidelines and Best Practices provide meaningful adaption of any new initiatives in an Organization. The industry experts who have seen the challenges and overcome with defined set of processes and tools, paving the way to govern the process in a consistent and standard fashion.
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.
This refers to the standard naming convention one should adhere to while naming API endpoints. As you are aware, HTTP methods emphasizes on the usage of verb. Thus the naming of endpoints should emphasize on the usage of nouns and avoid verbs.
In general, developers have tendency to name the endpoints based on method naming convention that popular programming languages follow - for e.g. getUsers. However, as per HTTP standards the naming convention will take verb usage of HTTP methods into consideration. For e.g., you will be naming the endpoint as "/users" that will result in GET /users as per HTTP standard. This provides better readability, easy to understand and maintain in consistency.
By versioning, you are allowing various conumers 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
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. For e.g.,
GET myapi/v1/users/123?format=json
GET myapi/v1/users/123?format=xml
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
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. For e.g. 5xx to indicate errors.
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.
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/authorize 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. Click here to see more details on top OWASP 10 principles.
You can also consider the following authentication/authorization 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 HTTP only
Ideal for consumer facing applications that authorize data for 3rd party access
OAuth 2.0 with bearer tokens is ideal for mobile applications. One can use JSON Web Token (JWT) which is becoming standard token mechanism as it is considered compact, hence the transmission is fast
"Great! We now have the strategy in place, understand the design principles and best practices necessary for the development of APIs. It is essential to understand the capabilities of api management platforms that address the non-functional requirements, changing business demands, and ways to accelerate the development and adaption of APIs. My next article would focus on the needs of API Management Platform."