Have you ever been thinking about API design guidelines for your APIs? Are all your APIs behaving the same way or are your API consumers struggling to find out how your APIs work?
If one or both answers to the above questions are negative, you definitely need to think about a company-wide API design and style guideline for your API designer and developers.
A well-designed API is important because it will promote easy adoption by your consumers. When all your APIs are designed and developed according to the latest standards, they will behave in the same manner and lead to satisfied consumers.
Also, when your company wants to expose its information through public APIs, these APIs represent your company. Think about a window through which your consumers will see and perceive your company. A uniform way of API design is important here too.
This begs the question: which aspects are key for good API design guidelines?
At AE we believe that the following characteristics need to be taken into account. Do note that some depend on the use cases, requirements and the maturity of your API developers.
Resources
The definition of your resources is probably the most difficult part in good API design. Think about the grouping of your resources. This can be done by business domain or by functional domain for instance. Also, make sure your resources are future proof by thinking broader than your current needs.
Define a consistent URI structure for all your APIs. This allows consumers know how to access your APIs and why the APIs are functionally useful for them. Also think about naming conventions.
Resource representation
Think about the representation of your resources. Define your request and response model and determine whether your APIs will use JSON, XML or another message format as payload.
But that’s not everything. Other questions that need to be answered are for example: Do your APIs allow multiple data formats and has the consumer the option to determine the format using content negotiation? Do you want a hierarchic or a flattened representation?
HTTP verbs
Determine the functional scope of your APIs. Do you only allow read operations or do you also support write, update or delete? Make sure to use the correct verb in all of these circumstances.
Status codes
The HTTP specification defines a lot of HTTP status codes, but not all of them need to be used in an API context. Make sure to define a restricted set of status codes and use them throughout your APIs.
Pagination
Make sure your response is paginated when read operations on collections occur. Today your result set might only contain ten entities, but within a few months this can reach 1000 or even more. When you decide not to use pagination you cannot guarantee the performance of your APIs over time.
Pagination can be implemented in different ways using the Link header, Hypertext Application Language, JSON-LD or Siren.
Filtering and sorting
Based on functional requirements filtering and/or sorting needs to be implemented. Make sure to specify how this can be done. Clearly mention whether you want to filter on resources and on resource representations.
Error handling
Do not only think about happy flow implementations. Enable your API consumers to take appropriate actions when something goes wrong by implementing a standardized error model for all your APIs to communicate meaningful (business) errors to your consumers.
Long-running transactions
Asynchronous is the way to go for long-running API calls. Updates in the backend that might take a while should be implemented asynchronously. Make sure to have a uniform way of defining asynchronous API implementations.
Versioning
Most likely your APIs will evolve over time. Make sure to determine a versioning strategy that fits your purpose. This can be no versioning, root namespace versioning or even resource model versioning.
When you put the emphasis on proper API design, your API consumers will be more keen on using your APIs. By exposing information in a structured way, you will also positively influence the perception your API consumers have about your company.
Do you have more questions about API design and API management? Or are you looking for a partner that can help you? Do not hesitate to contact us.