RESTful APIs should be Secured and Public by Default — An Opinion

Going strictly by usage patterns from a consumer perspective and a consumer not only includes paying customers but my software engineers, I’ve come to an opinionated conclusion that it is best from a long term maintainability and operation perspective to make all REStful APIs public but secured by default. Let’s avoid private, private internal and public endpoints. Instead, we have a single category: public but secured. You’ll notice I use the word customer or paying-customer.

A customer is a paying-customer and our internal staff, which includes engineering, PM or anyone within the organization. A paying-customer is exactly that… a paying customer.

I will cite several reasons for this and explain briefly the rationale using a few data points.

1. Accessing internal or private endpoints are a pain: To access and test internal endpoints you typically need to be behind the corporate firewall or connect to some VPN. What if I am working remotely or collaborating with remote employees or contractors? What if I need multiple VPN clients? Which one do I use? If testability is a primary consideration for system robustness, endpoints should be easy to securely access and test.
2. Internal endpoints are usually treated like second class citizens: These endpoints usually are developed to serve some internal ad-hoc or one-off need but eventually become useful. Usually these come from our services department to meet a specific customer need. They, therefore, end up with no documentation or are often times not compliant to the OpenAPI spec. After all, these are for our none paying-customers. Don’t be surprised to expend a significant amount of effort cleaning up these internal APIs as these were not engineered with the same quality standards as their public counterparts.
3. API documentation processes become more complex: When the time comes to create an API portal where your customers go for documentation of API endpoints, there becomes a contention from decisions to be made: Should we publish internal endpoints ? If so how should we hide them from the public as these typically are not secured. If we do not hide them, how should we publish them? Should we even bother publishing these to begin with? After all they are just for the developers. These guys and gals can go look at the code!
4. Then there’s the private and internal endpoints: Wait what? What’s private and what’s internal again? I thought private meant internal? And since no one takes the time to document these it becomes a never-ending source of confusion especially for new team members.
5. Lastly there’s a potential increased threat surface:. Unsecured APIs pose a security threat even if they are behind a firewall. If your organization suffers a security breach, your APIs are exposed. Secured APIs by default allows you to sleep at night as you do not worry about such things.

This sounds great, some would say, but what about my simple service which wants to do inter-service collaboration?

The short and sweet answer is: your service is just a customer of API and is treated just like any other customer, just like our own UI interacting with our APIs is just another client albeit with special privileges. Therefore, if your service wants access it should present the appropriate set of credentials which can be presented as an API key or access token.

But … private API incur less network hops. My standard response to that is we are prematurely optimizing.

What about rate limiting etc? I suspect that load balancing rules are actually easier when all your APIs are public.

With all the tools and resources to secure APIs today, including at a minimum authentication and potentially authorization, securing your APIs becomes a relatively trivial effort which will reduce your DevOps burden of maintaining private vs public as well as the operational and maintainability overhead that comes with it.

Keep it simple, keep it maintainable and happy coding!