LAST UPDATED August 18, 2023
What Is an API Schema?
The RESTful API design pattern is in use by an overwhelming majority of enterprise software projects that rely on machine-to-machine communication. The OpenAPI Standard, now in its third revision–OAS3–defines the functionality built into RESTful APIs, allowing automatic documentation, creation of test cases, and general “discoverability” of API resource specifications and service definitions. Colloquially, this OpenAPI Standard definition is called an API schema.
API schemas are critical in microservice mesh architecture, in client-server architecture, and in a great deal of automated tooling and build system automation. They’re also quite useful for adding another layer of security to your APIs.
API schemas give you the ability to define the expected usage of API endpoints, and then let you compare that definition to how they are actually being executed. With this information, you can then find the places where expectation and reality don’t match up and make informed decisions on how to respond.
API Schemas and the API Discovery Problem
Every development team operates a little differently, and all exist on a spectrum of maturity. Some projects have automatically generated API schemas. Some don’t. And, worse, some have partial schemas.
This spotty documentation of endpoint behavior compounds a common problem – one we hear about often from our customers – security teams don’t have visibility into production API endpoints.
Large enterprises have multiple API gateways, multiple hosting providers, multiple technology stacks, and multiple development teams. API endpoints are sprinkled across this heterogenous environment, and it can seem like dev teams are exposing new attack surface with every software release.
The teams in charge of operational security simply don’t know how many API endpoints they have, and they certainly don’t have full schematic definitions of how those endpoints should interact with clients.
Best Practices for Using API Schemas to Secure APIs
We’ve broken down a few steps to try to help make sense of this problem, and how to resolve it to secure API endpoints.
Step One: API Discovery
A good first step is to have some form of API discovery tool, so that you can get a good sense of:
- How many API endpoints you have
- How the APIs are being used
- What methods, calls, and data components are being exposed
- Who (what clients) are making those calls
Whether you have a schema or not, API discovery is a great first step to understand your overall exposure.
Step Two: Compare API Discovery to API Schema
A good second step, once you have a list of exposed endpoints based on actual traffic, is to connect that view of the world with the schematized view, created by your build systems. In practice, that list of exposed endpoints outlines a scavenger hunt – to track down schemas, understand intended behavior, and to compare and contrast that to actual traffic.
This means your API discovery tool needs to have the ability to ingest an OAS3 schema file.
But, there’s a catch! We often hear from customers that their application teams aren’t on top of their schema game; they have no schema files, or what they do have is incomplete or out of date. In this case, it’s important to break down observed traffic into methods and parameters, and to view it in what I call a “pseudo-schema.” This lets both developers and security administrators understand what APIs you have, and what risk they expose. You understand the methods and data components they should be supporting.
Step Three: Address Non-Compliant API Traffic
Once you have a pseudo-schema, you have a strong foundation for analysis. You can see if your client traffic passes the “sniff test,” and then you can make informed decisions about whether or not to block risky or suspicious (or outright malicious) traffic.
This last step allows you to make precise security decisions in the face of imprecise API definitions, and prevents a host of API attacks, such as those associated with BOLA, broken authentication, and excessive data exposure.
This means your API discovery tool also needs to be able to block traffic in real time.
For More Information
To learn more about best practices for API discovery and protection, see A Security Practitioner’s Guide to API Protection.
