You can now make a legit business case targeting developers as a market as the success of Twilio, Stripe, Github and others show. If you’re providing Anything-as-a-Service, an API is a must. Here are some qualities of a well designed API…
1. Intuitive
You’ll want to adhere to the principle of least surprise. Your API should come with a small surface area, with simple semantics, and a developer who doesn’t know the API can understand code written using it.
Intuitiveness comes from sticking to conventions — which starts with following standard HTTP status codes, borrowing terminology and concepts from other popular APIs.
2. Documented
You can never over-invest in documentation. You need three kinds of documentation catering to the various stages of the learning curve of a developer:
- reference: a comprehensive enumeration of endpoints, response/error codes and the shape of payloads
- quick start: a how-to style document for fast onboarding focused on a quick win
- tutorials: starts with a goal in mind and walks the developer through the process step-by-step, with simple answers to simple questions.
3. Opinionated
It’s important to be consistent across all your endpoints. Here are some areas you need to pay special attention:
3a. Entity naming
Use camelCase or snake_case, but don’t mix them both. You can see this mismatch in client libraries that don’t use camel casing against an API that does and the abstraction leaks through.
3b. Object IDs
Recommended to use:
- non-sequential randomized big integers
- serialized as strings
- a prefix to identify the entity type
You should send them as strings because certain languages have trouble representing big integers and truncate them — this is OK because you’re not going to be doing arithmetic with them. The prefix helps the developer identify what kind of id it is from a glance.
3c. Pagination
There are many ways to represent pagination. You definitely want to return the number of pages, the current page and items per page. You will also want to be consistent with how you request the next page or change the number of items per page.
3d. Timestamps
Always use ISO 8601.
Bottom Line
From my experience, the above checklist serves as a baseline of a good developer experience (DX) and saves your customers from doing integration busy-work.
Photo Credit: life’s too short.
