API Security By Design

Contrary to popular opinion, security is not a chore. And it should not be that difficult.

API Security By Design

After I got my PhD in theoretical physics, I decided I wanted to transition over from simple things like quantum gravity onto real challenges like writing maintainable Javascript and developing innovative approaches to API security. 

All jokes aside, contrary to popular opinion, security is not a chore. And it should not be that difficult.


APIs are fundamental to modern development patterns and a key factor to value creation in App and SaaS ecosystems. Currently, over 83% of web traffic consists of API calls, and this value attracts attackers. We’ve seen the amount of API incidents steadily rise year after year.

The first thing to remember when it comes to API security is that secure functions don’t always equate to secure processes

API security by design is all about breaking down how security considerations can be brought into the various stages of an APIs lifecycle and simplifying the API security process from the developers’ standpoint.

The 3 main security principles established by the CIA triad are integrity, or making sure the data is only modified in intended ways, confidentiality, which is largely about guarding access to the data, and my personal favorite, availability; because without availability, the other two are trivial to implement.

The Owasp Top Ten is another great source of information, though of course, it only covers the tip of the iceberg. However, when looking at the Owasp 2023 list, all of the vulnerabilities cited- such as BOLA, BOPLA, or Improper Inventory Management- can be traced back to issues with the CIA security principles. 

Recently, the White House has also been taking cybersecurity more seriously. The CISA (Cybersecurity & Infrastructure Security Agency) and 17 international partners published an update to the joint Secure by Design product, “Shifting the Balance of Cybersecurity Risk: Principles and Approaches for Secure by Design Software,” in a push to make security a top priority across development.

API Development

There are two vital parts of API development I’d like to draw attention to. These are documentation and versioning.

Documentation is one of the cornerstones of API development, as it is key for any form of collaboration. That being said, even in a single-person company, documentation should not be neglected. In fact, even if you are working on an entirely internal API with no external consumers, your future self will thank you years down the road for documenting your brilliant-at-the-time development ideas, speaking from personal experience.

Versioning is the second most important aspect of API development. It primarily helps API consumers in their development cycles, but it also helps with security issues such as debugging and forensics. For maximum effectiveness, you should have the version information present in responses and logs, et cetera. And it should not only be the endpoints themselves that have versioning, but data models and response data formats as well.

The figure illustrates a divide and conquer approach for DevSecOps teams. Organizing the field by API life cycle stages and stakeholder groups, we see that there are a lot of moving parts and  dealing with everything may not seem so simple. But it’s not as bad as it looks.

Most people focus a lot on the highlighted (best practices) which is definitely a key part of API security, and you could fill many books with all the best known practices out there- in fact, JJ Geewax and Arnaud Lorrett have both done so, so you should definitely check them out if you want more in-depth analysis on the topic.

I want to briefly mention the most neglected part of this table: compliance teams. Although to those not like me, it may seem like the most boring part of the process, there is really no excuse not to keep up with compliance, especially with GDPR fines on the rise. Incorporating a thorough compliance review early in the planning stage is crucial, as retrofitting audit quality controls into an existing system can be next to impossible, speaking from experience again.

Bang for Your Buck

Even though there are a myriad of aspects to consider, a few key tools and processes can help you cover a lot of ground when it comes to addressing the items detailed in the chart. I already mentioned documentation and versioning which will cover pretty much everything in the Design column, so we’re off to a good start.

The singular most helpful tip when it comes to security issues around the DevOps row is infrastructure as code. Speaking as a developer myself, there is nothing more satisfying than being able to deploy your entire service with a single command, having recovery time objectives measured in minutes not days.

Monitoring covers much of Operations and should be implemented from the get-go. Not having monitoring is like flying blind, it’s technically possible but just an accident waiting to happen.

Documentation is King

There are tons of tools out there for all of the parts I mentioned, but I’m going to focus a bit more on documentation tools.

The best-known and perhaps best overall option for documentation is OpenAPI (previously called Swagger), closely followed by API Blueprint. Both of these solutions sit in the “documentation as code” camp, which is to say they are human readable but can be used by automation tools.

The converse of this, “code as documentation,” consist of solutions such as GraphQL and Protobufs (used by gRPC). These can still be used to generate human readable documentation. 

The middle-ground category is JSON schema, which is a generic JSON validation framework which can be used for request and response validation, and many tools use JSON schema internally.

The main benefit of a proper documentation format, apart from providing a unified source of truth for all stakeholders to discuss and communicate about the API, is the tooling that the document format enables. Nearly every imaginable aspect of API development can be automated and orchestrated via, e.g. OpenAPI specification document; mocking, linting, sanitizing, validating, testing, authenticating, and more. 

It is important to note that these tools have limitations- for instance, authorization details are not covered by the OpenAPI specification, same for throttling and rate limiting, or session management details. All together though, researching and using the correct tooling for your API allows you to solve the lion’s share of problems you’ll be facing making documentation the single most important and helpful step in the development process.

Nowadays, most API threats target the business logic and application layers, which means applying a security focused mindset during API design is actually the most impactful security activity you can do for your APIs. When it comes to practical aspects of API security by design, comprehensive documentation, systematic versioning, and universal monitoring are the most important tools to apply in the API development cycle. API security can be daunting, but it should not be a chore, and once you break it down, it is really not that difficult.