The best API builders globally have API Design Guidelines to help them guide the development and design of their APIs. Great guidelines lead to great API specifications and which leads to great APIs.
However, writing guidelines can seem like a somewhat thankless task, whether they’re just for your own use, for your team or for a wider audience. Even if you see the merits, it can be hard to convince management to allocate time and budget for you to do it well.
To make writing your own API Design Guidelines easier, we’ve reviewed the guidelines of some of the world’s leading API builders and extracted the essential elements that you need. There are also links to some of the standout API Design Guidelines we review so that you can reference them directly.
The essential elements to include in your API Design Guidelines are:
- Approach
- Resources
- Methods
- Fields
- Errors
- Patterns
- Version Control
- Testing
Approach
API Design Guidelines need to outline the general approach or philosophy to be followed . This may seem obvious but in reality, people aren’t always aligned on what this might be
Most simply restate the principles of resource-based design or RESTful APIs. This includes restating some of the fundamentals as well as referencing the standards and papers behind these principles.
Here’s an example from Google’s API Design Guidelines on their philosophy of Resource-oriented Design and an explanation of RESTful APIs.
Resources
API Design Guidelines need to explain how API resources will be accessed. This is typically explained through how URIs will be structured but it can differ if the guidelines also cover newer API protocols.
The guidelines we reviewed all explained:
- How to design a collection of resources (e.g. /posts)
- How to design an API for a specific resource (e.g. /posts/234)
- How to design nested collections or specific resources (e.g. /posts/234/authors)
The better guidelines went into detail as to what an identifier for a specific resource or collection could be.
Here is how Atlassian provides guidelines on URIs for resources:
Methods
API Design Guidelines need to explain what standard methods are in your API along with how they are to be used. You also need to specify whether you will allow custom methods and, if so, how they can be designed.
The better guidelines just reused the standard HTTP methods of GET, DELETE, POST and PUT. Explaining how each needs to be used. Some also included HEAD, PATCH and OPTIONS.
Here is Google’s guidelines on methods:
Fields
API Design Guidelines need to define how to design fields that make up part of an API query.
This needs to cover guidelines for describing the fields themselves:
- The naming convention to use (e.g. camelCase, under_scores)
- How to describe a field
- The language to use
- Reserved words, preferred words or words to avoid
As well as explaining how to design the fields, the better guidelines we reviewed also provided definitions for commonly used fields. For example, you may want to describe fields like create_time, update_time, time_zone, total_items or order_by so that others can just reuse this.
Errors
API Design Guidelines need to define how your APIs will return errors, especially the most common ones.
This includes:
- Explaining the error format
- Guidance on your philosophy behind error handling and conveying errors to your consumers
- How to respond to errors, particularly common ones
- A list of common error codes or required error codes that each API must implement
Patterns
API Design Guidelines should provide patterns for common design challenges faced.
Here are some example of common API design challenges that benefit from having guidelines to explain how to handle
- Empty responses, such as no results
- Long running operations
- Handling files
- Pagination for when there are too many results to return
- Sub collections or sub lists
- Sorting
- Date handling
Versioning
API Design Guidelines need to explain how an API builder will handle versioning. Versioning is easier if it’s implemented from day one, rather than after the fact.
At a minimum you need to explain:
- Whether you require versioning or not
- How and where to specify the version (e.g. /v1/ or /1/ or /api?version=1.0)
- Different types of versions and their expected impact
Along with versioning, some of the better guidelines explained how to design for compatibility as well.
Testing
API Design Guidelines may explain how to design for testing. This wasn’t common to all of the guidelines we reviewed, but when it was there it stood out.
The guidelines around testing should explain the general philosophy and approach to help guide how APIs will be tested.
This is also where you can articulate how automation (if any) might help reduce some of the workload for testing. For example, if you automatically run certain tests based on the presence of something in the API specification, then it’s worth explaining that here.
You may also want to provide guidelines for how testing internally and by your consumers takes place. For example, you may run a separate test environment or you might allow developers to test against dummy data in production.
Other Areas
The purpose of this post was to focus on the essential elements. Of course, depending on the nature of your API program, you may have additional topics that you wish to include.
Guidelines Reviewed
You can go and check out a small selection of the better guidelines we reviewed: