Designing an API can be difficult, and it’s sometimes hard to know if you’re doing things right. How do you know you’re not making mistakes when building out your API? The real key to any good API is to keep it simple, intuitive, and scalable. Lucky for you, we’ve consulted with some API experts to gather some of the most common API mistakes so you can avoid them while you’re designing the best API!
Confusion Between APIS vs Services
This is by far one of the most common problems API developers face. When an IT team is running an API initiative alone, and are very familiar with Service Oriented Architecture, confusion can happen. The similarities between APIs and SOAs are there, however it doesn’t mean they are the same. When developers assume they are, the API can suffer. APIs need to be consumer oriented and based on business requirements.
Want to learn more about why API connectivity is important? Discover more about our free API-Led Connectivity Whitepaper.
Using http:// Instead of https://
Missing that single “s” can cause a catastrophe when testing an API. Some APIs may only support HTTPS, while others may support HTTP for some endpoints, but not others. Even when an API supports both, you can still run into errors. According to Runescope Blog: “For example, some APIs redirect HTTP traffic to their HTTPS counterpart, but not all frameworks will be configured to follow a 302 status code. Node.js `request` module, for example, will follow GET redirects by default, but you have to explicitly set `followAllRedirects` to `true` if you want to follow redirects to POST and other methods.”
Your API should support HTTPS, and it’s important to stay up-to-date with any changes in HTTP, as your API could stop supporting it. A good API provider will let users know beforehand through email or social media about any changes. The process for getting HTTPS certificates can be a hassle, but this blog from the CIO explains why it is very important.
Ignoring DDD
In a scenario where API specs are written in silos and involve overlapping domain entities, there may be a redundancy of effort, confusion, and possibly maintenance hazards that lead to reworking the API as a whole. According to MuleSoft expert Ali Salman Rizvi, “Imagine within a banking enterprise, if two lines of business – say retail and commercial – come up with their own version of API specs for processing payments; it will cause unnecessary redundancy at all levels.”
Not Specifying Content-Type of Accept Header
Accept and Content-Type headers negotiate the type of information that is sent or received between a client and server. Some APIS will accept requests that don’t contain them, and default to a common format such as JSON or XML. However, other APIs aren’t as lenient. Some may bounce back a 403 error if you aren’t explicit about the Accept header value, and will require you include those headers on requests. That way the server knows what information the client is sending and what format they are expecting to get back.
Developing APIs doesn’t have to be tricky. Check out our free white paper on API-Led Connectivity here:
