Bruno Pedro

API Friction

The concept of friction in products and applications is not something new and can be experienced by almost everyone. Product friction is represented by all the barriers and difficulties people find when trying to use a product.

Every Web site that makes you fill in a form, or wait for a confirmation e-mail, or take some test to prove that you are human is adding friction — and losing sales. — Pogue, 2012

API friction is the resistance that an API offers to anyone that wants to integrate with it. API friction happens when developers try to understand what an API is and how it works and find it difficult and cumbersome. API friction also occurs further down the line when problems are found, and there’s no way to report them. Let’s look at a list of all the things that might increase API friction.

  • Difficulty in understanding what the API is: questions such as “what can I do with the API?” and “how can I start?” should be easy to answer by anyone trying to use your API.
  • Difficulty in testing the API: developers and integrators should be able to quickly see the API working and test it in mock mode. The API should also have a sandbox where tests can be performed without affecting real data.
  • Bad or non-existent documentation: API documentation should be easy to find and understand. Documentation should provide a full reference and also guides that help developers get going quickly.
  • Lack of alignment with your use case: the API doesn’t provide operations that make it easy to implement specific use cases. Moreover, it’s hard to understand how certain use cases can benefit from using the API.
  • Lack of SDKs: there are no SDKs officially supported by the company providing the API. There might be community-supported SDKs, but they’re out of date or buggy.
  • Weak community: API community is small or non-existent. If it exists, it’s not supported by the company behind the API. It’s hard to find information online about other people using the API.
  • Bad support: official API support is non-existent or bad. Support requests often take a lot of time to get answered or are simply ignored.
  • Too much work needed: the amount of work needed to integrate with the API is overwhelming. By the time the integration is finished the API has already gone through a series of changes.
  • Copyright and legal issues: “If we permit companies to copyright APIs, it will disincentivize developers from opening up new services as APIs or, at the very least, slow down the development process.” — Sarid, 2016

Have you been experiencing API friction lately? How do you think you can avoid it?