Shift left with these 6 Spectral rules

APIs enable developers to connect with internal and third-party services, making them crucial building blocks for modern applications. Today, it’s essential for teams that are working on APIs to follow established software development lifecycle (SDLC) best practices, such as “shifting left” with continuous integration and deployment (CI/CD) pipelines. While these best practices take time and effort to implement, they ultimately reduce the amount of overhead that is required to release quality APIs, meet customer needs, respond to changing market conditions, and mitigate security risks.

Spectral rules are a powerful, well-documented, and widely adopted set of standards that help teams ensure their API specifications are secure, well-formed, and compliant. Applying Spectral rules consistently and automatically at the earliest stages of development and throughout the CI/CD pipeline enables any organization to fully integrate a mature API development strategy into its overall software development efforts and meet business goals.

In this post, we’ll discuss six Spectral rules that can be used to improve the quality, security, and compliance of APIs. But first, let’s explore the benefits of shifting left in an API context.

The benefits of shifting left

In the traditional “waterfall approach” to software development, developers are solely responsible for creating new functionality. Issues that arise in development are therefore not caught until the subsequent testing phases, when they are costly to repair. This trend is evident in the graph below:

To address this problem, more and more organizations are “shifting left” by migrating their processes to CI/CD pipelines. With CI/CD, teams can automatically test new code at every stage of the development process in order to verify its quality. As a result, defects (represented by the orange line on the graph) are identified and mitigated during the “Planning” (not shown here), “Coding,” or “Unit Test” phases, when the costs to repair them (represented by the red line) are still low.

Shifting left is especially crucial to the API lifecycle because APIs are usually produced and consumed by different teams—or even different companies. As a result, issues can become deeply ingrained in both the producer or consumer’s codebase and require a lot of time and effort to resolve. Teams therefore need to define a comprehensive set of API tests that can be executed at every stage of development and within CI/CD pipelines.

By running tests consistently and repeatedly—on both a manual and automated basis—teams are able to resolve issues quickly and cost-effectively while mitigating any risks to the API’s security.

6 essential Spectral rules that can help you shift left

Spectral rules can be used to validate the quality, security, and compliance of APIs at every stage of the API lifecycle. The rules detailed below are often overlooked, resulting in a dramatic and negative business impact.

Rule 1: Enforce HTTPS

This rule may seem obvious, but no development organization that claims to have a scalable, comprehensive, and secure API strategy can be lax in checking this bread-and-butter correctness rule. In the worst-case scenario, this problem goes unchecked until it is public-facing and coupled with an incorrect API gateway configuration, leading to public exposure. It’s worth noting that if this problem does surface publicly, the severity of the problem and the cost to fix it will both be enormous—especially given that the cost of guarding against it with a Spectral rule in Postman is nearly $0.

Rule 2: COE-enforced API governance

This is not a specific Spectral rule, but it is enforceable with Spectral rules. An organization doesn’t need to have much API maturity in order to run basic functionality tests on its APIs, but a general best practice is for these rules to be defined by either the engineer who implements the API (in the case of “code-first”) or the person who defined the API (in the case of “design-first”). Unfortunately, team members whose primary responsibility is to create functionality and innovation tend to not police themselves as rigorously as they should. As an organization matures, it should therefore develop a center of excellence (COE), which is responsible for the following:

• Collecting best practices from across the organization, so that all teams can benefit from the lessons learned by individual groups.
• Collecting industry best practices from outside the organization.
• Determining which best practices should be adopted in order to meet the organization’s specific needs. These best practices might include enforcing naming standards, security standards, process standards, or other uniformities.

Rule 3: Info license

APIs are intellectual property, and every single one needs to be protected with the proper licensing. This should be done not only for public-facing assets, but for private assets, as well, in order to protect them from breaches.

Legal protection of intellectual property should also extend to the following rules:

• Terms of Service
• Version
• Contact Email

Rule 4: No empty paths

This rule identifies two or more slashes that appear next to each other in a URL because a string has been omitted. This issue may sound relatively benign, but it can actually open an endpoint up to attack.

For instance, suppose that a specification was generated by another utility, the URL paths were built dynamically, and that some variable was unexpectedly set to an empty string. This chain of events resulted in the following URL endpoints, two of which are correct and one of which has an error:

• https://<host>/a/b/c/d/func1
• https://<host>/a/b/c/d/func2
• https://<host>/a/b/c//func3

Once deployed, the best-case scenario is that we have a route advertised that is not actually implemented:

• Advertised: https://<host>/a/b/c//func3
• Implemented: https://<host>/a/b/c/d/func3

But, depending on how the implementation is deployed, we could potentially wind up with a callable URL endpoint in a web directory that’s not set up properly or properly permissioned to serve that resource while limiting access. You can assess the risk by asking these questions:

1. What are the access permissions in https://<host>/a/b/c ?
2. Specifically, are the access permissions in https://<host>/a/b/c more liberal than the ones in https://<host>/a/b/c/d ? This could be the result of the web server getting set up without “least privilege” best practices, and no one having yet tested access at the higher directory level.
3. Is this an admin-level function that we’re considering? Is it a function that should otherwise be behind an authentication wall?

Security personnel will say that there should always be zero trust, even between different tiers of a single application. For instance, the application tier should never blindly assume that the platform tier or the infrastructure tier will always protect it, and vice versa. This particular rule therefore addresses a top-tier security concern within the realm of API specification problems.

Rule 5: Enforce authentication type

Security and authentication workflows have significant monetary value and organizational importance, as they protect the organization’s brand and revenue while ensuring proper alignment with internal and external compliance standards. To illustrate, let’s consider a hypothetical example.

A public-facing API that is being offered as a product could depend on scores of other APIs, all with particular authentication needs that vary depending on their security context at the time of use. For instance, one group of APIs may be intended for pre-production use, so they only require the use of an API key or some type of bearer token. Production API use, on the other hand, requires SAML authentication to support B2B interaction and OAUTH to support B2C interactions and to allow users to sign in using their Google or Facebook credentials.

This hypothetical scenario is highly complex, and it has security and billing implications that carry a high cost of failure. But a real-world problem is even more complex. For instance:

• APIs call other APIs and often relay security context. As a result, fixing such a problem may involve multiple development groups and code bases—as well as significant build time—to advance the fix through the CI/CD pipeline.
• On the other hand, APIs call other APIs and often don’t relay security context. If the public or customer-facing API is not properly secured, this erodes the security of the second API, which could have access to far more sensitive information or functionality.
• If an authentication problem reaches production, the organization is not protected and may also start billing incorrectly, since authentication is the process by which the caller is identified. This issue therefore has potential revenue implications.

Rule 6: Example response

The API specification itself is the means by which CI/CD processes and all of their groups, individual stakeholders, sub-processes, and automations coordinate. As such, the importance of a comprehensive list of example responses in an API specification cannot be overstated. The following scenarios illustrate how examples can save both API producers and consumers time and money:

• An API consumer needs to build a product that will call a particular API, and examples help them code the product in a robust manner that can appropriately handle all possible error cases.
• Without adequate examples, API consumers often lose time trying to figure out how to choose and format data appropriately.
• If an API producer provides a mock server to serve sample responses, API consumers can begin to code their product with calls to the API before the first viable version of the API is complete. This not only shortens consumers’ end-to-end development time by allowing them to proceed while the API is still in development, but also reduces pressure on producers to release an initial viable implementation that is buggy, feature incomplete, or not fully contract-compliant.
• When advancing an API implementation and its specification from stage to stage, automated contract tests need to be executed in order to verify the integrity of the state change.

Example responses should always be provided for the following:

• Each “class” of response that an API is capable of giving. If an API can return multiple formats, it’s essential that each one is documented.
• Error codes and the error conditions they indicate.
• The format of every piece of data. If an API caller does not know exactly what to pass in as an argument, both the documentation and the API spec designer have failed. Here are some examples:
  • Birthdate: mm/dd/yy or dd/mm/yy or dd MM YYYY
  • Store ID: integer value between 1 and 9999
  • First name: string of at most 30 characters
  • Plan Type: { “string1” | “string2” | “string3” }

Conclusion

Every business has different objectives and will therefore value each Spectral ruleset differently. Nevertheless, the Spectral rules we discussed in this post can help teams detect and avoid universal problems that can result in enormous and unexpected costs. Running these checks manually and automatically within CI/CD pipelines and at every phase of the API development process ensures that any issues are resolved as quickly as possible—and with minimal consequences for the customer, the business, and the brand.