Why are APIs so hard to use? - Part 3
Continued from the second part HERE.
We continue our series on why APIs and microservices are so difficult to consume and integrate. In our second section we covered the issues of API patterns and organization. Now we will discuss advanced API issues.
Poor or inappropriate abstractions can be the biggest dangers in using APIs. Sometimes APIs and microservices provide exactly the right abstraction to meet application requirements. For example, Google Firebase cleanly abstracts a database into a REST API that can conveniently vary by the database schema it is deployed against, which makes it exceptionally easy to expose a database to the internet.
At the other extreme, APIs may completely lack some valuable abstractions. For example, Twitter lacks a function for determining whether a certain key or token has a particular permissions scope. If a programmer wants these abstractions, they must code them for themselves. Sometimes the mismatch between requirements and API abstraction is more subtle. For example, many user list endpoints provide a nested denormalized object that is describing the user and all other related entities in one API endpoint. Unfortunately, the platform will only have one user endpoint, which requires all data to be loaded into memory; if a query to that endpoint has millions of results, then it becomes necessary to implement custom logic in order to conserve memory.
There are a variety of reasons why a programmer might have to settle for an API with inappropriate abstractions. Perhaps no better API even exists. Perhaps the company lacks money to license a better API. Or perhaps the API has become part of the company’s infrastructure and cannot be easily changed. In any such case, choosing an API with inappropriate abstractions makes the programmer’s job more difficult. All too often, the assumptions built into one essential API will conflict with the assumptions built into another essential API. Each such conflict makes the API user’s job more difficult.
Strategies of API Consumers and Users
One attribute of successful programmers is the well-developed ability to imagine and implement new abstractions. That way, when a given API fails to satisfy a particular requirement, a supply of appropriate abstractions is at least conceptually available. In fact, efficient programmers maintain personal toolboxes of already-implemented, ready-to-reuse abstractions. Cultivation of reusable abstraction implementations has proven to be a valuable strategy for many programmers coping with the inadequacies of an API.
For large multi-person projects, this investment can pay off even before the current software ships, but it may benefit other projects, as well. Of course, the documentation strategies mentioned earlier for API designers also apply here. Unit tests are valuable because upgrading the API implementation may cause a function that previously met a requirement to stop functioning properly. At some companies, policy dictates that engineers must write unit tests for every new class. This policy can pay off quickly when using open source APIs, which can evolve rapidly and with little warning.
In light of the challenge of evaluating and navigating the conflicting assumptions of APIs, most API users seem to take whatever API is handy and build from there. Later, as necessary, they incorporate additional APIs. If adding a certain API seems too difficult, then they skip it and “shop” for an API that fits better. In the average case, such a strategy will allow the application to grow without a huge amount of the “brute force hacking” alluded to above.
Strategies of API Publishers and Designers
API designers can do much to ensure that the API’s exposed abstractions match requirements of concern to prospective users even though they can’t provide abstractions for every single user’s application requirement. Ideally, matching abstractions to as many requirements as possible helps to make the problem smaller for API users, who can “check off” more requirements using API functionality. The BitScoop API integration platform can help by empowering your microservice abstraction with a basic service API and then customize with granularity using BitScoop API Maps.
Several factors govern this strategy of producing functionality that suits the application requirements of the API user. Each abstraction should be deliberate, rather than mimicking idiosyncrasies in the underlying primitives used to implement the API or microservice. Part of why APIs can sometimes seem inappropriate for some needs is because it can be very difficult to find a perfect list of API endpoints that match all of the business functions your system needs to perform. This is more than an API documentation problem, as it often comes about because API designers fail to keep conceptual chunks reasonably sized. For example, APIs should not have an excessive number of endpoints, and hierarchies should not contain more than a few levels. Anything larger is too difficult to effectively grasp. Bloated lists of endpoints, parameters, and arguments exemplify bad architectural decisions calling for abstraction, redesign, or a breakup into sub-APIs.
Common themes recur in good programming strategies. Always try to make the problem smaller. The overall problem is to map requirements to a new application. Divide this problem into smaller parts, each of which can be conquered (and composed into a larger solution). “Make the problem smaller” applies to other strategies, as well, such as consciously ignoring part of the problem because a solution to that part already exists.
When possible, accept approximate or imperfect results when necessary. Software engineers accept and implement easy requirements that satisfy most of clients’ needs and then push back on less important requirements that would take very long to implement. The result is an application that is almost ideal from the customer’s standpoint, yet still affordable.
When working on something new, pick an approach that is efficient on average. Sometimes a programming strategy quickly leads from requirements to application; sometimes a strategy does not work so well. As you mature your skills and try new approaches to projects, keep in mind the methods that worked best for given situations. Conquering a new task will require improvisation, sometimes at the beginning. Find the approach that works for a broad range of problems when starting from a blind spot.
Themes like these are typical of any engineering discipline, and they undoubtedly appear in other strategies for similar API-related challenges. As software engineering continues to mature, themes like these will hopefully diffuse throughout the discipline’s textbooks and curricula so that new programmers will be better equipped for facing the APIs of the real world. This is why the BitScoop platform is so compelling; it adds the properties of abstraction, modularity and extensibility to the heart of any software stack.
These are only examples of what can slow you down when developing with APIs and how the BitScoop platform can solve these issues with BitScoop API maps. Check out our current community supported API map list and see the possibilities of our new API paradigm. Users are only beginning to explore what is possible on BitScoop. Should you have any questions, don’t hesitate to reach out at https://bitscoop.com/support.
