Snyk’s shift left approach to API development

Snyk’s developer security platform provides developers and security professionals with the tools they need to build and operate modern applications securely. Snyk enables users to shift security left and to embrace a DevSecOps model. Modern application development teams understand that shifting left means bringing information to developers' fingertips as early as possible in the development process to create efficient and secure applications and development processes.

At Snyk, we are embracing this same shift left model as we develop the APIs and applications that power our platform. API development, like other specialized tasks, requires the development of specific processes and the usage of the appropriate tools. As an API-first platform, it is crucial to get feedback on our API contracts as early as possible. Snyk’s APIs give users — inside and outside of Snyk — access to our industry leading security products. Developers rely on Snyk and our APIs to power their SDLC and to enable them to build secure applications. Providing high quality APIs is critical to our platform’s success, and having a high quality API development process is critical to providing users with those APIs.

This blog post will explore some of the processes and tools Snyk is using to create our API-first platform.

Why shift left?

Software organizations have long understood the value of shifting left for testing, operations, and security. Instead of waiting for reviews to happen later in the SDLC, developers can get feedback quickly using techniques like continuous integration and tools like Snyk’s IDE plug-ins. The result is faster delivery, improved security posture, reduced costs, and an overall more trusted application delivery process. When developing APIs, the same shift left approach is applicable.  It’s better to get feedback early, ideally with automated tooling. 

Style guides and Snyk’s approach

Developing RESTful APIs is a particular type of application development that requires the right process and tools. Snyk’s V3 APIs are designed to provide users with reliable, consistent, easy to understand, and innovative ways to interact with the underlying platform. At Snyk we define our APIs using OpenAPI (a.k.a. Swagger), the de facto standard for defining RESTful APIs. However, simply having our API specification in a machine and human readable format does not mean that the APIs will meet our goals around usability. Users need the APIs to be consistent across the entire platform so that they can easily interact with different parts of the platform with ease.

To provide a consistent API we need stylistic standards. Many organizations use a style guide to provide content creators with instructions for how to create a consistent tone and style for their writing. Snyk has developed our own style guide for API development. It is our API Stylebook for teams creating APIs. As our organization scales and more developers are creating APIs, our API style helps us build consistency into our APIs so that we provide a consistent developer experience for our users. But having the style guide is only part of the solution. We also need mechanisms to help our developers ensure that they are complying with the guide.

One solution to compliance is providing a manual review. Since our APIs are specified in OpenAPI and maintained in version control, we can follow the same review process for API definitions that we follow for other code artifacts. Developers can create pull requests (PRs) for their API changes and have a colleague provide feedback. This manual process can be an effective way to ensure compliance, but like all manual processes it is subject to human error and not always timely. Snyk is a globally distributed, remote first workplace. Waiting for a colleague to review your API PR can result in a slow turnaround that hurts productivity, especially when it comes to aspects of the review process that can be automated. This is where our approach to shifting left with automated API reviews is helpful.

Snyk developers who are building APIs have the three ingredients necessary to execute a local automated process of review:

• The Snyk API standard expressed as a series of rules

• The API they have written in OpenAPI

• Linting tools that can validate that the OpenAPI specification the developer has written is complying with the specification’s rules

Developers with local linting tools for their APIs are able to get real time feedback on their APIs. This enables Snyk developers to correct issues with their API before getting to a manual review step. The linter can also be integrated with our CI jobs to check for compliance. Because all development teams use the same rules the Snyk platform can provide a more consistent API experience for our users.

Partnering with Optic

Once we made the decision that we would represent our data model with REST, we began to define our API standard with JSON API. Once we had a draft of a standard, we set out to make it executable — a standard-as-code to avoid blocking development teams with an “expert API review.” We aimed to provide rapid feedback as part of our shift left philosophy.

The initial tooling we found for building these rules was great at syntactical verification by pattern matching, such as linting for valid OpenAPI 3. However we quickly found the limits of this approach when applying it to implement our API standards. Such rules are tedious to read and write (JSONPath and regexes), and they can only express constraints on what is in the current version of the API specification being evaluated. We decided we needed a more robust solution, and found that Optic was a great option for us.

Optic is a partner looking to shift left in their API Review and Governance products, and supports API design-first workflows. The outcome of our work with Optic in this space is Optic CI, an API linting product capable of expressing our API standards. Optic CI rules are easy to read and write as a high-level Typescript DSL. Most importantly, Optic CI embraces the same reality of API development that Snyk has: APIs are always changing and evolving. The rules operate over the changes in an API, rather than a point-in-time. Such rules are flexible enough to drive continuous improvement and refinement in our APIs, and govern this change without aggregating a mountain of “lint exceptions” as the standards themselves are refined.

More on the way

Snyk is committed to creating a developer-first and API-first platform. By shifting left in our API development SDLC we bring feedback to our developers. Stay tuned for our next post on Snyk's API development process, in which we'll explore how we are using tooling to manage versions for our API.

Want to be a part of the team building the Snyk platform? Browse our open Engineering positions and help us in our developer security mission.