A public-facing API is a good way for others to connect to your systems. But don’t start building one until you answer these questions.
There’s a lot to be said for creating an API and making it publicly accessible. Public-facing APIs enable people to connect to your systems, which can extend a business model or simply make things easier to accomplish.
For software creators, a public-facing API makes it easy to open access to the application’s data and services to third parties, developers, partners, and internal teams. This advantage also benefits enterprise organizations because businesses regularly need to bridge the gaps between different systems for integration and data sharing.
But as with so many other endeavors, the first time you embark upon this sort of project is the hardest. We all prepare for the problems we expect to encounter, but we’re stymied by the questions we didn’t ask. You don’t know what you don’t know.
That’s why it’s good to seek advice from experienced developers — the people who learned their lessons the hard and painful way. We asked dozens of experienced technologists a single question: What do you wish you knew before you started implementing public-facing APIs?
Versioning, versioning, versioning
Any great developer will tell you: if you learn about API versioning after your API releases publicly, then you’ve learned about it too late.
“Versioning allows you to develop multiple versions of your API, which enables you to keep adding new functionalities and endpoints without breaking the existing API users’ workflows,” explained Brett Lindenberg, CEO of Mindstamp. But after you advertise an endpoint and others use it, any change you make can impact their workflows. That has an impact on both the provider and the consumer.
One CTO learned this the hard way. One of his company’s projects involved building a comprehensive API for a healthcare client. The API facilitated data exchange between hospitals and third-party diagnostic services.
“We underestimated how changes to APIs without proper version management could disrupt the user experience and lead to significant integration issues for our clients,” the CTO said. When it released a new version, the consulting firm had to keep track of how to test for backward compatibility. “Our tech support line was going crazy, so we had to hot-fix the APIs to get them working again.”
Versioning ties into your depreciation and end-of-life strategy and process. “You can’t be backward compatible forever,” the CTO pointed out. So we told our customers that they had to be on this version by a certain date or the API wouldn’t work.”
Here’s the decision and design process recommended by one experienced developer who believes strongly that you should put version numbers in every payload:
Classically, endpoints are versioned in the URL: /foo/V1/XXX and /foo/V2/XXX, etc. Some may debate where the version number should be located, but the point is that endpoint versions are differentiated with different URLs. If a large semantic change is made to an endpoint, then maybe this makes sense.
But more often, the change is in new or changed request attributes, or in a successful return payload’s attributes. I have found it easier to put the versioning in the payloads: that is, one of the payload attributes is the version number. And in the return result, one of the payload attributes is the version number. A new extra argument or a change in an attribute’s unit/meaning is deciphered by the payload version number.
In both versioning schemes, there’s different client and server code for V1 vs. V2 calls. There’s less and/or more localized surgery with a payload version scheme.
In whatever way you address the mechanics, take the time to think through your design choices. “API versioning is not just a best practice; it’s essential for maintaining functionality and ensuring service continuity for users as the API evolves,” said the consulting company CTO said. Without it, every update risks breaking compatibility with existing clients, forcing them to adapt to changes that could have been seamlessly managed.”
Document everything. Everything!
For many developers, application documentation is an afterthought. When it comes to developing public-facing APIs, however, you absolutely should address it up front. Always consider how documentation will be implemented, written, and published.
That applies to both the human/developer documentation and its technical design. “Most suck,” wrote one developer succinctly.
“I wish I had known how important detailed documentation was before I started building public-facing APIs,” said Rajesh Namase, cofounder at TechRT. “Coders need clear and complete documentation to understand how the API works, including its endpoints, parameters, authentication methods, and error-handling steps.”
Users who try to connect with the API are frustrated when the documentation is unclear.
“Make detailed instructions that developers of all skill levels can use,” urged Namase. Also, make sure the manual stays up to date, reflecting API changes and improvements. Strong documentation also builds trust and credibility among users, which improves the API’s image and encourages widespread use.
Design and document the interfaces
Treat the API like a product, the experts suggest. Use the same tools and techniques you’d use for any large-scale project: prototypes, user testing, feedback channels, and so on.
API design and implementation are broad subjects, enough to justify an entire book on them. (Mike Amundsen’s Design and Build Great Web APIs: Robust, Reliable, and Resilient was recommended.)
“I talk in my class about the difference between the shallow API interface — the list of documented functions, their parameters, what each one does — and the ‘deep’ interface, which is the correct and useful combination and sequence of API calls required to complete a given task,” one computer science professor offered. “A lot of API documentation covers the shallow interface but neglects the deep one.”
One element of documentation is the API’s data formats. “I spent a lot of time on the data formats, especially trying to make life easier for the client for parsing,” said Steve Mushero, a fractional CTO for several startups who wrote about his API design process at length.
And surely you don’t need to be told to conform to standards while you construct your APIs and their documentation, especially for error messages? For example, RFC7807 “defines a ‘problem detail’ as a way to carry machine-readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs.”
Though as Mushero commented, “I added a unique error code like AUTHHEADERMISSING that was mostly human readable but to be used in client’s logic not dependent on parsing messages etc., and for when HTTP codes aren’t enough.”
Another other developer chimed in: “Don’t misuse HTTP error codes for business-level errors. Instead, return a 200 (OK) with an error code and message in the return object specifying the business-level error.”
Another resource is the AIP design documents that summarize Google’s API design decisions. Those documents provide a framework for others to document their own API design rules and practices.
As one developer explained, “They are the result of a lot of folks at Google who’ve spent time standardizing Google APIs in response to customers asking ‘What do you mean API 1 takes datetimes in this format and API 2 takes datetimes in this other format?’”
While Google’s APIs are not necessarily the best model for your situation, the company’s guidelines can give you a sense of the number of decisions to make and how much the opinions vary.
Define the testing process
How will you deploy and test endpoints?
“Testing your API is critical to ensure you are delivering the correct data to the correct users,” stressed Mindstamp’s Lindenberg. “Misconfigured APIs are the source of most data leaks around the world. By adding automated testing alongside manual testing, you can be sure your API is secure, performant, and completing the tasks that it should.”
For example, be sure to test the system under heavy load. What happens when someone hits your endpoint with lots of requests?
Perhaps the lesson or counterargument is: Build in throttling from the start, as you absolutely will need it.
“It’s better to first release the endpoints and then add throttling,” one developer said. “You need to live through a DoS attack (intentional or accidental) just once to realize that’s a risky bet.
Once the API is published even to Beta testers, you only need one bug in the nascent client code to accidentally cause a DoS attack.”
Consider architecture and tooling
And then there’s… everything else. Not everything fits into a well-organized summary.
Contemplate the developer’s journey through the API. “Companies make APIs around their data model, not around the job to be done,” one developer advised. That results in complex orchestration sagas and call sequences. Within that journey, how will the developer get consistent, clear feedback on design consistency, validation, and error messages?
As with so many other software development topics, there rarely is a single right answer — but take the time to consider how you’d respond to the obvious or not-so-obvious questions.
One software engineer began with this list of organizational and architectural questions:
- How is auth going to be handled?
- What backpressure mechanisms, rate limiting, or other flow control mechanisms will clients support?
- What is the standard error format: RFC7807? Something else?
- What standard pagination format will be used for “list-like” queries?
- How will you implement tracing and observability?
- How will you separate auth and cookie-related elements from other properties on the site?
- What do health checks look like?
- How will asynchronous tasks be implemented? What is the standard format for a deferred task ticket?
- What UIDs will you use to uniquely identify resources?
- What protocols do you want to support? JSON? GraphQL? WebSocket? WebEvents? Protobuf?
- How will inputs (and possibly outputs) be validated in a standard fashion?
Do you have answers to these questions? You should.
At Growth Acceleration Partners, we can help you work through all these issues and come up with the best answers for your organization. Let us know if you’d like to chat.
