Introducing Twilio’s guardrail

Introducing Twilio’s guardrail

We’ve all been there, alternating between JIRA and a blinking cursor wondering “What does this API even look like?”

That question is the bane of productivity and a spoiler of successful cross-team collaboration. Attempts to consume anything other than a perfectly documented API hit speed-bumps, if not  complete show-stoppers.

You may have heard of Swagger, OpenAPI Initiative‘s API specification language. With Swagger, we can write a specification file as well as consume it programmatically via tools like Swagger Editor, swagger-api/swagger-codegen, or anything capable of reading and verifying JSON Schema. Today we’re proud to introduce guardrail, a framework for providing principled code-generation in type-safe languages and frameworks.

API Documentation: progress over perfection

One challenge for a microservice is to adhere to its contracts. As we’ve already seen, it’s possible to document the overall structure of an API fairly accurately. Given that fact, how do we ensure we conform to the published specification?

One way to ensure conformance would be to derive the specification programmatically via tools like swagger-akka-http. For existing codebases, tools like this are invaluable for exposing and managing existing infrastructure without incurring significant engineering overhead. Providing an existing API’s surface area via a programmatically consumable specification is the first step towards API excellence.

Make illegal states unrepresentable

One significant downside with automatic specification generators, however, is the diligence required while maintaining annotated services. At the risk of sounding hyperbolic, any mistakes, omissions, or undocumented routes immediately throw the validity of the generated specification into question. If we can’t trust our specification, what do we have?

For that reason, we decided to reimagine how swagger specifications can be used to express correctness. By generating an abstract interface with concrete types that completely insulates the business layer from the underlying HTTP layer, we get very close to what we want.

Instead of attempting to extract correctness from code, we leverage the typesystem to ensure correctness, every time you compile. Need to respond with a different HTTP Status Code? Add it to the spec and the next time you compile, it will be there for you. Changing the existing specification? Once again, the type-system is here to help, ensuring the desired structure is correctly exposed.

For your consideration, Twilio’s guardrail

That’s why we’re pleased to announce guardrail, a framework for providing principled code-generation in typesafe language and frameworks. We’ve initially targeted the Scala language, as well as Lightbend’s akka-http web framework, although experimental support for http4s clients has been added recently.

For those interested in the internals of guardrail, the core is written using typelevel/cats, as well as the fantastic scala.meta. Extension is possible via providing alternate implementations of the core term interpreters, which we do internally at Twilio to support internal metrics libraries and code guidelines.

We here at Twilio are extremely excited to join the broader Swagger community, as well as to provide a platform to help ensure API quality for all.

Devon Stewart is the tech lead on Programmable Fax, an amateur photographer, and passionate about quality software. You can find him in the coffee shop, in the gym, or making his way up a trail on his mountain bike. You can reach him on Twitter at @blast_hardchese