A design mistake can ruin an otherwise perfectly good API. It's important for API designers and developers to learn what the most common API design mistakes are, and how to fix them, in order to create APIs that developers will want to use. Luckily, in this blog we identify a few of the most common API design mistakes, and go over how the issues can be solved.
According to Jason Harmon, head of APIs at Typeform and the namesake of the JSON schema, there are three big things that go wrong in API design. One big lifesaver when it comes to designing an API is to use HTTP POST instead of GET. GET is the go-to method for building filtered queries in HTTP, but using it can result in confusingly long URLs. While this can sometimes be good for discovery by Google, and good for SEO, Web apps that work through the browser can face problems when using GET. This is, according to Harmon, because browsers like Chrome are good at caching, and if the browser sees a seemingly repeated GET, you may get two landing pages for one submission.
Even if you get by a browser, you have caching proxies on your provider, especially with hotels and ISPs, and they will redirect cached GETs even if you tell them not to. You often don’t know what they will and will not cache." -Jason Harmon, Head of APIs, Typeform
To overcome that problem, Harmon recommends changing your GETs to POSTS, as the HTTP specs for POSTs don't cache.
Want more information about APIs? Check out our free whitepaper, API-led Connectivity.
When an API consumer, like a Web application, calls an API over and over again it's said to be "polling" the API. This usually happens when the consumer expects some data to change on a regular basis and is looking to get the latest version of that data. If consumers are calling on average of once every five minutes, the net result could be a huge number of calls. “A quick solution for us was to set up webhooks, which are a kind of a reverse API. Instead of them asking, we send them a POST when there is something new,” said Harmon.
Aside from webhooks, Harmon offers these solutions as well: caching (which is difficult,) or a read-only database replica.
The microservices structured version of Typeform's forms are Harmon's example of how to correctly architect an API when not everything has to be updated in one shot. Updating everything at once for Typeform required seven separate API calls, causing the API's performance to bottleneck. One solution offered for this is to drop REST for a GraphQL-driven approach. However, in the meantime Harmon developed this workaround:
Harmon's team broke the form up into a microservice-like structure that bound certain commonly chained back-end activities together in order to more efficiently service the the front-end and weed out unnecessary API chatter. Forming a backend-for-frontend (BFF), a layer of server-side JavaScript (Node.js) deals with the orchestration when responding to calls. This is a way to turn a rigid resource structure to your advantage.
When it comes to building an API, the path to success is to build them for the user first. “When you are building APIs, think about how people use it. We call it API design, but we tend to think like engineers,” Harmon said. “Have some empathy for the people that are going to use it. And when you really do this you can figure out quickly the problems ahead of time.”