Intuitive API Developer Experience with Nolan di Mare Sullivan from Speakeasy

The outcome of a good API Developer Experience is that a developer interacting with your API is able to maintain a flow state. Their concentration is not broken by needing to deduce the behavior of an opaque system.

“We’re entering a period of intense competition in the API space.”, says Nolan di Mare Sullivan, Head of Developer Relations at Speakeasy, where he is making it easy for developers to create and consume APIs.“Users have limitless options available to them for any given functionality required in their application. If you aren’t providing API users with a good API experience, you’re encouraging them to check out competitors.”And when he says good API experience, he means good developer experience for engineers interacting with your APIs. 

Closing the gap between developers’ intuition and the product

In theory, the best developer experience is the one when the gap between the developer’s intuition and the actual functioning of the product is non-existent. In practice, some gaps are inevitable and should be addressed with easily accessible information to resolve issues. In other words, good API documentation.The desired outcome of a good API developer experience is that a developer interacting with your API is then able to maintain a flow state; Nolan continues: 

“Their concentration is not broken by needing to deduce the behavior of an opaque system. Instead, they can work on honing their unique application code without worrying that the systems they rely on will trip them up”.

Start with an SDK

Intuitive API design may sound simple, he says, but a lot goes into making an API experience magical for your users. “The best place to start is with an SDK (software development kit) for your API. A well-built SDK provides several impactful benefits to users:

• Type safety - SDKs can enable IDE errors, giving your users the ability to proactively address issues as they write code. They will be spared the frustration of having to comb through constructed data objects to find mistakes after a failed request.
• Request and response formatting: SDKs can handle the details of formatting requests and parsing responses in a format that is specific to the API. Users will no longer have to worry about which parameters belong in the path and which in the query string. Pagination will be available out of the box, making it easy to parse large responses.
• Error handling: SDKs can interpret the details of errors that occur when using an API and respond accordingly. That means no more custom retry logic for customers to write.

What makes a bad API developer experience?

If the main characteristic of a good API developer experience is that it’s intuitive to use, a bad developer experience would be the opposite: unintuitive. “Unintuitive experience most commonly stems from APIs that don’t adhere to commonly established standards or lack consistency across their interface, says Nolan, and illustrates it with an example:“Imagine an API that has an endpoint for searching for a user and another for searching for a product:

 
    /user/1234/search/
 
    /product/find?id=1234

This would offer a terrible developer experience. 

As a developer, it would be reasonable to assume that the search mechanism would be the same for the different resources exposed by the API, but in this case, that’s not true. In the user endpoint, the user_id is a path parameter, while in the product endpoint, it’s a query parameter. Additionally, the API routes vary in terminology: search & find.

”The consequence for the developer trying to integrate such an API is that they are not able to take anything for granted:“They would need to double-check every aspect of their requests to make sure they matched the documentation.”

How does a bad API experience happen?

There is no company in the world purposely making it difficult for developers to integrate their APIs. So how come bad API developer experience is more common than not?

Nolan thinks the answer lies in the organizational challenges companies face.

“In the case of an API, that leads to there being no thought given to the holistic experience of using the API, i.e., no stylistic consistency. Every team manages their individual fiefdoms, and the experience of using the API is disjointed and illogical. It happens far too often.”

The solution? If you can’t change the org chart or the way of working, there is still centralization and automation.

“You want a way to centralize style without creating a bottleneck in your API org. I would recommend organizations to build frameworks that introduce automation into the API development process."

Done right, automation is a boon to the teams building the API, making them significantly more efficient. Simultaneously, automation reduces the number of individual choices developers need to make and can introduce the consistency that creates a great end-user experience.”

Conclusion

Nolan emphasizes the importance of an intuitive API Developer Experience. The key to a successful API is ensuring that developers can maintain a flow state without being hindered by the need to understand an opaque system. A good API experience is characterized by its intuitiveness and ease of use, bridging the gap between a developer's intuition and the product's actual functioning.

Key points to achieve this include:

1. Good API Documentation: Essential for addressing inevitable gaps between developer intuition and product functionality.
2. Start with an SDK: A well-built SDK (Software Development Kit) can provide type safety, handle request and response formatting, and simplify error handling, significantly enhancing the developer experience.
3. Avoid Unintuitive Experiences: APIs should adhere to established standards and maintain consistency across their interface. Inconsistencies lead to a poor developer experience, as developers cannot rely on their assumptions and must constantly refer to documentation.
4. Address Organizational Challenges: Often, disjointed and illogical API experiences stem from organizational issues, where different teams manage their sections independently. The solution lies in centralization and automation, introducing consistency and efficiency in the API development process.

In summary, the goal is to create an API experience that feels natural and seamless for developers, enabling them to focus on their unique application code without unnecessary complications.