API Design Principles - Quick Overview

Every software architect or developer has used and developed API's (Application Programming Interface) in their day-to-day work. API's provide a level of abstraction for the functionality of an application. A good API design is very essential to make the API useful to its consumers thereby increasing its adoption.

I have been asked about a quick overview of API design principles many times and I must admit that it was very difficult to encapsulate all the principles that I have used, in a short overview answer. Yes, there is a large amount of material available in terms of articles, podcasts and guidelines on API design. However, there is a common thread that runs across these and my attempt here is to pinpoint those common principles for a short and quick overview.

Following is an overview of common API design principles :

1. APIs must be designed as per the business domain model and the operations that can be performed on domain entities.
2. APIs must use standard and consistent set of operations for all resources. For Read APIs, filtering, sorting and pagination must be supported by design.
3. APIs must provide clear and consistent feedback regarding the status of the operation. Long running operations must use asynchronous mechanisms (e.g. callback URLs) with a response which indicates that the operation is registered.
4. APIs must be secured. Consumers who use the API must be authenticated and authorized. API data shall be encrypted as it passes across system or organization boundaries. Sensitive data must be encrypted during transport even within organization boundaries.
5. APIs must be versioned by design so that existing consumers can continue with their usage while new consumers can take advantage of the new versions of those APIs.

Here's a brief description for each of the above principles:

APIs must be designed as per the business domain model and the operations that can be performed on domain entities.

APIs must be designed as per the business domain model so that it enables its consumers to understand the API easily. For e.g. the API "/orders" allows consumers to manipulate Order entities OR the API "/accounts/transactions" allows consumers to manage transactions on an account. The API should not expose the underlying data sources (e.g. database tables).

APIs must use standard and consistent set of operations for all resources. For Read APIs, filtering, sorting and pagination must be supported by design.

For e.g. any read operation could have "get" prefix (getOrders / getCustomer) and write operation as a "set" prefix (setOrder / setCustomer) in standard Java modules. In the REST API style, standard HTTP methods must be used to ensure consistent usage like,

• GET to retrieve resources (GET /orders),
• POST to create resources (POST /orders),
• PUT to update resources (PUT /orders).
• DELETE to delete resources (DELETE /orders)

For Read API, parameters can be used to provide filtering, sorting and pagination. For e.g., getEmployees(FilterCriteria, Page) OR in REST style

GET /employees?filter=dept:Accounts&sortBy=first_name&offset=1&limit=25

APIs must provide clear and consistent feedback regarding the status of the operation.

The API feedback can be as status codes or error codes with additional relevant information regarding the status of the operation. For e.g. a successful create or update operation can always have a return code 1000 whereas errors could be denoted with specific error codes in a range denoting the various error possibilities. In the REST API style, HTTP status codes must be used for API status feedback. For e.g. 201 - resource created, 200 - resource updated, 404 - resource not found, etc. must be used.

APIs must be secured. Consumers who use the API must be authenticated and authorized. API input and output data shall be encrypted as it passes across system or organization boundaries. Sensitive data must be encrypted during transport even within organization boundaries.

APIs can be authenticated using a username/password mechanism or API keys etc. Based on authentication, it must be verified if the API consumer is authorized to invoke the API. Data security can be typically implemented using TLS (Transport Layer Security) or HTTPS.

APIs must be versioned by design so that existing consumers can continue with their usage while new consumers can take advantage of the new versions of those APIs.

There are different ways API can be versioned like URI versioning (/api/v1, /api/v2) OR using version attributes in query OR using HTTP headers for version etc. API versions allow the API developers to enhance functionality of existing API's without requiring rewrite of all consumer clients that use the original API.

Final Thoughts

It is clear that API design is an iterative process and there are many other considerations while designing APIs depending on the specific application and business domain. However, above design principles shall definitely ensure that APIs are usable and adopted by consumers easily.