This is the blog of Adam Kalsey. Unusual depth and complexity. Rich, full body with a hint of nutty earthiness.
Developer Experience Principle 3: Easy to Build
Freshness Warning
This blog post is over 3 years old. It's possible that the information you read below isn't current and the links no longer work.
5 Oct 2020
Once a developer has Discovered your product and decided to use it, you have to get them to stick with you. You can do that by making developers more productive. Building on your API should be a joy, not a chore. Many developer products have a great developer experience on the surface. Fewer focus on those building and maintaining robust applications. Developers thrive when it’s Easy to Build things that are more complex than Hello World.
For REST-based APIs, developers can make HTTP calls from any programming language. But if you were to look at their code, you’ll find they’re all doing the same things. They’re wrapping API calls with error handlers. They’re converting JSON and XML responses to language-native data structures. They’re writing functions that combine responses from many API requests.
You can make the lives of your developers easier by building SDKs and libraries that do all this for them. Strive to supply one for every language that’s popular among your customers.
The SDKs you create should feel friendly to experts in the language. Every programming language has its own idioms, and your library should respect those. Avoid using idioms to the point of obfuscation, though. Concepts like lambdas, promises, or lazy loading can be complex and can make your SDK unclear. The syntax a developer writes to work with your SDK should be like the syntax they would write in the rest of the application.
You can go beyond making friendly syntax. You can add syntactic niceties that help a developer be more productive. When your API has several steps that are often combined together, your SDK can offer a single operation that combines them.
Your API documentation can also show recipes for common operations. Helping developers implement common patterns and themes will save their brainpower for solving unique problems instead of learning how to do something everyone else has already learned. For example, if a developer needs to look up rates and shipping company IDs before creating a shipping order, include code samples that show those steps together in the order they should happen.
One way to make developers more comfortable and more productive is to make it easy for them to do the right thing. Using intelligent defaults will make it easier for developers to build on your APIs. Instead of forcing developers to supply every parameter every time, default to the most common case or the best way of doing things.
Your documentation code samples can also help developers do the right thing. Developers will write code the way they read it in the documentation, so you want your documentation to show the best way to do it, not just the easiest way to document. Write your code samples like they’ll be used in production. Because they will.
A corollary to this: if you’re finding something hard to explain in the documentation, it’s too confusing to use. Simplify the product instead of improving the documentation.
One place that can become confusing to the developer is inconsistency. Your API and SDK design needs to be consistent throughout. The order of parameters to a function should be the same on similar functions. Error codes and messages must be consistent between different API calls. Use a single date format everywhere. The terminology in your documentation should match the terminology used in your APIs. Use the same words in your API reference that you do in your long-form tutorials. If your company has many API products, try and make this consistent across all your products.
When something goes wrong, help the developer. It’s easier to build when you’re not having to puzzle through the problem with vague, incomplete information. Write descriptive error messages. Reading the error message should give the developer enough information to correct their problem. Where more detail is needed, include a URL to your documentation on the subject. Make your error messages searchable by publishing documentation with the exact contents of each error message and helpful troubleshooting information.
Provide tools developers can use to debug their applications. Logging every request and the responses of each can be invaluable in determining if a code is sending what the developer thinks it is. A dashboard that shows all errors helps a developer manage their production usage. Alerting on increased error rates can help developers manage their deployments.
To go beyond the basics, think about the day-to-day workflow of a developer. Unit tests for API-driven applications can be hard to build. Testing alternative flows for error conditions is especially hard. Providing developers with a mock API that will return known responses for requests can solve this. The mock API (or even the real API) can even include ways to cause intentional errors or alternate flows. Sending a tracking number of 1Z111111111 could return a delivered package, 1Z111111112 a rejected one, and 1Z111111113 a lost package.
Plugins for popular IDEs are not hard to create and can help developers work faster. Code completion is an easy first step. Adding documentation, syntax highlighting, or templates can help developers build. Start small and add more features as you improve your IDE support.
A product makes it Easy to Build by focusing on productivity for developers building real-world applications. Think beyond the samples, the hackathon snippets, and the Hello World tutorials. Give your developers the tools to build robust applications and maintain them over the long term.