Forem: Phil Sturgeon

There's No Reason to Write OpenAPI By Hand

Phil Sturgeon — Fri, 24 Apr 2020 14:28:30 +0000

Some API developers use API descriptions to plan the interface of an API before building it, which is known as the "API design first" workflow. Others build the API then generate (or manually produce) API descriptions later, which is the "code-first" workflow. We wrote API Design-first vs Code-first recently to help get you up to speed on the differences, but how do you actually create these API descriptions?

Many of these API descriptions (OpenAPI, JSON Schema, or GraphQL Schemas) involve writing out a bunch of special keywords in YAML, JSON, or another text language. Neither the design-first or code-first crew enjoy writing thousands of lines of that by hand. Why? Well, say you've got a list of integers:

  schema:
     type: array
     description: List of IDs
     items:
       type: integer
       description: Pet ID

Designing an API with 100 endpoints like that will get you through at least one keyboard (maybe two if it's a Macbook). Designing a few APIs could drive you bonkers.

Let's look at some alternatives to hand-rolling your own homegrown artisanal YAML, and how these approaches fit into design-first or code-first. More importantly, let's see how they can be used to achieve the ultimate goal for API designers: one source of truth for API descriptions that power mocks, documentation, request validation, shareable design libraries, and more.

Annotations

Some programming languages support a syntax-level feature called "Annotations", for example Java Annotations. An OpenAPI annotation framework provides a bunch of keywords that help the API developer describe the interface of the HTTP request and response, and hopefully it's telling the truth.

class UserController {
  @OpenApi(
      path = "/users",
      method = HttpMethod.POST,
      // ...
  )
  public static void createUser(Context ctx) {
      // ...
  }
}

Some languages do not have any support for annotations, and they achieve this with docblock comments.

/**
  * @OA\Get(path="/2.0/users/{username}",
  *   operationId="getUserByName",
  *   @OA\Parameter(name="username",
  *     in="path",
  *     required=true,
  *     description=Explaining all about the username parameter
  *     @OA\Schema(type="string")
  *   ),
  *   @OA\Response(response="200",
  *     description="The User",
  *     @OA\JsonContent(ref="#/components/schemas/user"),
  *     @OA\Link(link="userRepositories", ref="#/components/links/UserRepositories")
  *   )
  * )
  */
public function getUserByName($username, $newparam)
{
  // implementation logic ...
}

In JavaScript it looks a bit like this:

/**
 * @swagger
 * /users:
 *   get:
 *     description: Returns users
 *     produces:
 *      - application/json
 *     responses:
 *       200:
 *         description: users
 *         schema:
 *           type: array
 *           items:
 *             $ref: '#/definitions/User'
 */
app.get('/users', (req, res) => {
  // implementation logic ...
});

This approach is the oldest around, and is primarily used by the code-first people. It's easy to understand why: you wrote the code already, so now lets get some docs! Sprinkle some keywords around the code, and the annotation system will integrate with your framework to emit a /docs endpoint, and boom, you've got some documentation. Great, if all you want is documentation.

Design-first people also sometimes use this approach. They design the entire API (writing YAML by hand or with one of the other approaches we're going to mention), then use Server Generators like openapi-generator or swagger-generator to create their API code. This API code is created from the machine-readable documents that were made in the design process, and the code that is generated is chock full of annotations already, which in turn can generate documentation. Throw those machine-readable documents away, the annotated code is the source of truth now... right?

One downside to annotations is that they don't confirm the code is doing what it says. I've heard the argument "Annotations are closer to the code they describe, so developers are more likely to keep it up to date". Do not confuse proximity with accuracy. Developers can forget to make the changes, and developers can make mistakes.

Annotation users need to find a way to contract test the actual output against these annotations, which we've written about before in Keeping Documentation Honest.

The tools in this article generally involve the machine-readable OpenAPI / JSON Schema files around, so you need to export them back to a machine-readable format in order to compare them to the code... This means running a command in the command line which pulls the annotations out into a machine-readable file, then running a tool like Dredd or a JSON Schema validators, which is a pretty awkward step.

Design-first is incompatible with all this, unless you chose to design the API, then generate code with annotations, then figure out how to keep the code, the annotations AND the machine readable designs up to date. If there's anything worse than two sources of truth it's three...

For this reason, folks who like design-first run and hide from annotations, but the folks who like annotations generally really really love them because to them their code is the source of truth and if they can crowbar one of these test suites in to confirm that then they're perfectly happy. This mindset can lead to API clients being a bit of an afterthought, but that's another topic for another article.

DSL (Domain Specific Language)

A few DSLs popped up over the years, created by people who wanted to create API Descriptions, but didn't fancy writing it out in that specific format, with articles like Making OpenAPI / Swagger Bearable With Your Own DSL.

DSL's can be used in code-first or design-first. You have your code, you have your DSL-based descriptions, and whatever format they were written in doesn't make much difference here.

;;; ENTITIES
(define pet-entity
 (entity "Pet"
    'race (string "What kind of dog / cat this is (labrador, golden retriever, siamese, etc...)" "Labrador")
    'origin (string "Country of origin" "Egypt")
    'birthday (datetime "Birth date of the pet" "2017-10-20T00:14:02+0000")
    'species (string "What kind of animal is this" "dog" #:enum '("dog" "cat"))))
(define $pet (schema-reference 'Pet pet-entity))

;;; RESPONSES
(define list-pets-response (jsonapi-paginated-response "List of pets" ($pet)))

;;; REQUESTS
(define pet-request (json-request "Pet Request Body" ($pet)))

;;; MAIN DOC
(define swagger
 (my-service-api-doc "Pet Store" "Per store pets management"
   (path "/pets") (endpoint-group
      'tags pet-tags
      'parameters (list store-id-param)
      'get (endpoint
              'operationId "listPets"
              'summary "Retrieve all the pets for this store"
              'parameters pagination-params
              'responses (with-standard-get-responses 200 list-pets-response))
      'post (endpoint
              'operationId "createPet"
              'summary "Create a new Pet record"
              'requestBody pet-request
              'parameters (list xsrf-token)
              'responses (with-standard-post-responses 200 single-pet-response)))

This is shorter than the OpenAPI YAML it replaces, but it's also another format for people to learn. People who know how to write up OpenAPI will need to learn this format, and the folks familiar with a different DSL will have to learn this format too. Your editor will also need to learn about this format if you want autocomplete, syntax highlighting, linting and validation. The "native" description formats all have this, but these DSLs usually do not.

This approach, just like annotations, do not help you ensure that what you're writing in the DSL is actually correct. The contract written down in the description could be completely incorrect. Some DSLs like RSawg aim to solve this by having their DSL be written as integration texts. The source of truth for how you create OpenAPI is literally integration tests:

describe 'Blogs API' do
  path '/blogs/{id}' do
    get 'Retrieves a blog' do
      tags 'Blogs'
      produces 'application/json', 'application/xml'
      parameter name: :id, :in => :path, :type => :string

      response '200', 'blog found' do
        schema type: :object,
          properties: {
            id: { type: :integer },
            title: { type: :string },
            content: { type: :string }
          },
          required: [ 'id', 'title', 'content' ]

        let(:id) { Blog.create(title: 'foo', content: 'bar').id }
        run_test!
      end
    end
  end
end

This approach is pretty handy for Test-driven development (TDD) advocates, but you're just writing OpenAPI in another form which isn't particularly any shorter, just more Ruby-ish. RSwag was a big favourite at my last job, but it's had a rough time getting updated onto OpenAPI v3.0 (still a work in progress 3 years after OpenAPI v3.0 was released).

Writing in a DSL or annotations means you're at the mercy of that maintainer to support functionality that you could already use if you could just... edit the OpenAPI yourself.

Graphical Design Editors

What is the alternative to editing the files but now having to wrangle YAML? Visual thinkers and non-technical people might want a wizard mode, the ability to create arrays of objects with a few buttons, and selection boxes for shared models without having to think about the filepath. Graphical design editors are pretty new in the world of OpenAPI and GraphQL, with a few popping up over the last year or two.

Stoplight Studio main form editor view, showing some the $ref selector for picking OpenAPI models.

Two years ago I was looking around for a beautiful, effective graphical editor to satisfy some code-first sticklers pushing back against API design-first at WeWork. I figured a GUI would help them convert, and Stoplight told me they were planning a new GUI. Shortly after seeing their amazing prototype I joined the company to help roll it out to even more folks, and now my job is gathering feedback from the API community to make Studio, our open-source tools, and the upcoming SaaS platform even better. 🥳

Modern GUI editors have mocks and docs publishing built right in so you no longer have to figure out your own "DocOps". Editors like Stoplight Studio add "Design Libraries", where you can manage shared models between multiple APIs in an organization. These editors support organization-wide style guides to have the editor lint during editing (and/or in continuous integration) to enforce consistency, and a bajillion other things.

Stoplight Studio with Spectral linting results from a custom rule written to stop folks designing a GET endpoint with a body.

There are a bunch of different OpenAPI-based graphical editors around, check out our list on OpenAPI.Tools:

GraphQL fans, who are having a lot of the same conversations right now, can check out these:

Some editors will help you with part of the API design life-cycle, but make a lot of difficult assumptions about what order you're going to do what in. They might help you create a design, then they'd assume you wanted to export it and generate some code, leaving your machine-readable description documents floating around to become obsolete, and giving you no way to edit them even if you wanted to. Other tools let you import an OpenAPI document, but convert it to their own internal format and provide no way to pull the OpenAPI back out again.

Using tools where the format changes entirely at different points locks you into whatever workflows they support, instead of letting you plug-and-play your own tooling at every stage of the process. For me the ideal solution is supporting a git-based flow, where they live in the repository (maybe before the code exists), and regardless of how these API descriptions were created you can edit them and send a pull request back to that repo with the changes you made.

Leaving the machine-readable source of truth in the repo means any integrations are possible. Continuous integration processes can deploy documentation to any documentation provider, you can use use any code-generators to build and publish SDKs, sync with popular HTTP clients like Postman or Insomnia instead of maintaining API descriptions and bookmarks, and fully take care of contract testing in-repo or end-to-end repositories. If your editor is backed by a design library then the repositories will be analyzed on push, allowing others to use these updated models instead of having 1000 different versions of a "User", "Company" or a "Flight".

The main Stoplight Explorer dashboard, providing search across all APIs in an organization. This has only been available for Enterprise users, but is available for everyone this April.

But, how does having an editor help you catch mistakes? Stoplight Studio has a built in HTTP Client, which amongst other things is watching for mismatches between the OpenAPI defined for the API and the actual HTTP requests you send. It will also notice mismatches between OpenAPI and the responses coming back, so you'll see mistakes popping up like this:

Noticing contract mismatches in a HTTP client is all well and good for spotting mistakes in requests you're making, but you'll want to automate this checking too.

Instead of having all your model validation rules and header checking written in code, and then also writing it down in the API descriptions, use the existing machine-readable descriptions for validating incoming requests. If your request logic is powered by API descriptions, there is no need to check that it matches the code, because it... is the code. Framework middlewares for every framework and every language implement this. NodeJS has about 100.

PHP: league/openapi-psr7-validator
Node.js: fastify / express-swagger-ajv-validator / express-openapi-validate
Ruby/Rails: committee
Python: connexion
Perl: Mojolicious::Plugin::OpenAPI

The Rails one, for example, takes a single line to set up the Rack middleware:

use Committee::Middleware::RequestValidation,
  schema_path: "./openapi.yaml"

That covers incoming requests, but how to ensure the responses are doing the right thing? Some of those middlewares will implement response validation too, which can confirm the response coming through it matches the code. This is a great thing to enable in dev and staging, but turn that off for production. 🤣

Another approach to checking responses is contract testing. Instead of having some DSL-based integration testing suite specifically for checking the responses, or using some other tool where you have to write out the contract again, you can can just use the API descriptions as contract tests. So easy, and all it takes is a few lines of code to mush the response into a data validator for the API description format of your choice.

Another approach is using Prism Proxy in end-to-end testing to blow up if any requests or responses are invalid throughout the test suite. This can be implemented with little to no buy in from the folks producing the APIs, because you can just funnel existing cross-API traffic through the proxy in the testing environment without modifying any code.

Code first and editors do not jive at all, because the editors do not understand the annotation system in the Java/PHP/Pyhton/etc sourcecode. According to an extremely scientific poll on my Twitter, 35% of teams are battling through with a mixture of code-first and design-first.

So long as the code-first folks add a build step (pre-commit or in CI) to generate a machine-readable file in the filesystem (like openapi.yaml), then hosted solutions like Stoplight Platform can analyze repo contents to give the same hosted docs, mocks, and design libraries, to all the projects. No editing for them of course, but those who want editors are on the same remaining workflow as those who don't. 🥳

Annotations-as-Code Web Frameworks

Many web-frameworks third-party support for request/response validation, which we've mentioned above. This is usually in the form of middlewares or just baked right in, and they read API descriptions from the filesystem.

Other frameworks have first-party or third-party support for annotations, which are purely descriptive repetitions of the actual code they sit above at best. At worst they're just lies.

There is a new category of API description integration popping up in some web frameworks which is somewhat like Annotations or DSLs, but instead of being purely descriptive it's actually powering logic and reducing code, giving you one source of truth. Effectively they do the same thing as the machine-readable powered validation middlewares, but instead of coming from openapi.yaml the logic is coming from the annotations.

Here's an example from tsoa, which is a TypeScript and NodeJS framework for building OpenAPI-compliant REST APIs.

import { Body, Controller, Get, Header, Path, Post, Query, Route, SuccessResponse } from 'tsoa';
import { User, UserCreationRequest } from '../models/user';
import { UserService } from '../services/userService';

@Route('Users')
export class UsersController extends Controller {
  @Get('{id}')
  public async getUser(id: number, @Query() name: string): Promise<User> {
    return await new UserService().get(id);
  }

  @SuccessResponse('201', 'Created') // Custom success response
  @Post()
  public async createUser(@Body() requestBody: UserCreationRequest): Promise<void> {
    new UserService().create(request);
    this.setStatus(201); // set return status 201
    return Promise.resolve();
  }
}

This is a brand new approach. Instead of descriptive annotations or comments shoved in as an afterthought, the API framework has been designed around the use of annotations.

Beyond simple things like request validation, TSOA handles authentication quite nicely. Numerous times I've seen API documentation say bearer tokens are required, or an OAuth token needs a certain scope, only to find out the developer forgot to register that in the API controller. Free sensitive data anyone?

TSOA solves that by having you register security definitions, then reference them in your annotations, and have middlewares created to handle the actual logic. This way the annotations are all the actual source of truth for authentication, instead of just being lies in comments or YAML.

Then, OpenAPI can be generated from a command:

tsoa swagger.json

Whilst I definitely have a preference for design-first development for all the prototyping benefits it brings (changing a few lines of YAML in an awesome GUI is easier than rewriting a bunch of code every time you get feedback on a prototype), this new approach for making annotations useful is very much closing the gap. If you're going to use a code-first approach, you should absolutely try and find a framework like TSOA to power your API and reduce the chance of mismatches.

Ideally the file-based middlewares and these new annotation-driven middlewares would share a bunch of dependencies. As I mentioned before there's a million of these file-based validation middlewares out there, and some get more love and attention than others. I convinced three PHP request validation middleware authors to combine efforts and make one amazing one, so it'd be great if some of these other middleware developers could team up with some annotations-as-code framework people to allow them as inputs to their existing middleware. With OpenAPI v3.1.0 coming out soon, it'll be a lot better for us tooling vendors to start collaborating on a smaller number of higher quality tools, instead of everyone battling through the upgrade process individually.

Whatever you're up to: code-first, or design-first, make sure you're doing what you can to avoid maintaining two sources of truth. Of all the options possible, try and stick to:

a) awesome editors like Stoplight Studio or GraphQL Designer to maintain API description documents, then reference them in the code, or

b) frameworks which support annotations-as-code that knows how to express itself as API descriptions

Just don't maintain code and descriptions separately, because having two sources of truth just means waste time trying to find out which one of them is lying.

Automated Style Guides for REST, GraphQL and gRPC

Phil Sturgeon — Tue, 05 Nov 2019 20:48:20 +0000

Ask 100 developers where a semicolon should go, and you'll either get 100 answers, or a all-on-all fist fight. To save this from happening at work, most folks implement a style guide, which beyond helping with consistent style to avoid new developers getting shouted at for "doing it wrong". Linters can advise best practices, shout about things which are technically allowed but likely to cause trouble, and shape the API of code as it's being written (snake_case that method!) This is always done for code, and is becoming increasingly popular for API descriptions.

JavaScript users have eslint, PHP users have PHP Code Sniffer, and Ruby has rubocop. These linters don't just check that the user is writing valid syntax. They check against existing sets of rules, sometimes written by a company, like the almost defacto-standard eslint-airbnb. Sometimes the rules are made by standards bodies like PSR-12 by the PHP-FIG, and the tools create a ruleset to match, like the PSR-12 ruleset for CodeSniffer.

Today I even had to use awesome-lint in order to make sure awesome-earth was conforming to their rules, which were built using the Remark Markdown linter.

When it comes to API descriptions, most companies of a certain size end up with a "Style Guide", "Style Book", "Design Guide", etc. These are often on a Google Doc, wiki, or some other sort of docs/content management system. I've seen loads of these, and written plenty. Many companies even publish them.

Text-based Style Guides are a Time Suck

The trouble with these text-based documents is that they are large, terse, unexciting documents, which developers rarely read. If developers do read them cover to cover, and remember everything in there, that knowledge becomes partially out of date when new rules are added because they won't know about them until they re-read everything cover to cover again.

At API the Docs I saw a talk from Kelsey Lambert at Salesforce, and their style guide is an example OpenAPI description document which they ask people to check now and then when they are working on something to get ideas of the sorts of things they should use. Salesforce... The giant company with 238479347 APIs who maintain 40 major versions per API, their style guide enforcement approach is eyeballing and memory. Agh I feel for you folks! I have been here and it was bad.

No developers can be blamed for any of this mess. API developers are busy, and the folks writing style guides are just trying to figure it out as they go along. This mess is an industry problem, but thankfully tools have popped up which can enforce these same style guide concepts through automation.

api-linter by Google
graphql-doctor by Cap Collectif
graphql-schema-linter by Christian Joudrey
Spectral by Stoplight

Each one of these projects sets out to do relatively similar things, but for different types of API.

Spectral for HTTP APIs

Spectral is a JSON/YAML data linter, with built in rules for OpenAPI v2/v3 and JSON Schema.

Running the default OpenAPI ruleset on the average document will find plenty of suggestions, which can be helpful for developers not entirely familiar with OpenAPI. Something as small as reminding people to add parameter-descriptions can help make human-readable docs more useful, and they might not have even realized that was possible.

You can use Spectral to create rulesets, and these rulesets can have custom rules, and even custom functions!

These custom rules can look a bit like this:

rules:
  schema-names-pascal-case:
    description: Schema names MUST be written in PascalCase
    message: '{{property}} is not PascalCase: {{error}}'
    recommended: true
    type: style
    given: '$.components.schemas.*~'
    then:
      function: pattern
      functionOptions:
        match: '^[A-Z][a-zA-Z0-9]*$'

This one is a popular one. OpenAPI does not care how you capitalize your models, but a lot of code generators will use the model names for code, and having inconsistent class names will upset people.

Let's take it a step further:

rules:
  paths-kebab-case:
    description: Should paths be kebab-case.
    message: '{{property}} is not kebab-case: {{error}}'
    severity: warn
    recommended: true
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(\/[a-z0-9-{}]+)+$"

This rule is actually looking beyond the metadata of your API descriptions, and is looking at the actual API design itself. This is saying that the "paths" (endpoints) must be hyphenated, so /recent-files is good but /recent_files is not ok.

You can start to get really creative with this.

rules:
  no-x-headers:
    description: "Please do not use headers with X-"
    message: "Headers cannot start with X-, so please find a new name for {{property}}. More: https://tools.ietf.org/html/rfc6648"
    recommended: true
    given: "$..parameters.[?(@.in === 'header')].name"
    then:
      function: pattern
      functionOptions:
        notMatch: '^(x|X)-'

I don't know why but at some point during the lifecycle of any given API, some developer will suggest adding an X-Foo header, despite over a decade of it causing issues. Well, we can keep them outta here with this rule.

Done early enough, this will shape the actual API as it is being developed. If you are doing code first then ok, you have to go back and change a bunch of code. Hopefully you didn't ship it, because now you need to go and make a bunch of redirects for /recent_files /recent_files. If you use an API design first workflow, then you notice this early on when you've just got some YAML, and your API gets built right in the first place.

Seeing as Spectral is a CLI/JS tool, enforcing this style guide can be done
in all sorts of ways.

in a git hook
in a JS test suite
on continuous integration to fail builds with errors

If you're using Stoplight Studio then it's baked right into the editor, so people designing APIs just do it all correctly straight away. No need to alt tab away to the CLI or wait until a PR is made.

I am trying to find time to take a style guides from Heroku or PayPal and turn them into a huge example ruleset. At the very least, I can take some inspiration for a new ruleset I'm putting together: The OpenAPI Contrib > Style Guide. This should be an interesting community effort.

Spectral also has a GitHub Action and a GitHub Bot which we are working on improving. Commenting on ranges and suggestions coming soon! 😎

GraphQL Doctor & Schema Linter

GraphQL has it's own built-in type system, which has some of the same sort of keywords as OpenAPI / JSON Schema based stuff.

GraphQL makes some design decisions easier, like how you handle relationships. No need to pick between nesting/embedding related resources, inlining everything with a compound documents, or using hyperlinks to link to related data, GraphQL decides that for you. Still, there is a lot of inconsistency that can occur outside of the default decisions GraphQL makes. GraphQL people do not escape the need to lint, but luckily a great linter exists: GraphQL Schema Linter.

Custom rules can be written for this one too, so you can automate your style guide in CI. No bot or GitHub Action that I can see, but they aren't too tough to knock together.

One schema tool in GraphQL land with a great bot is GraphQL Doctor. It seems like it wants to help with a lot more linting in general, but so far it is focused on detecting breaking changes. Like any type system, there is a fine line between careful evolution and recklessly changing stuff, and GraphQL Doctor will spot the latter.

It would be nice to see the two tools merge, or maybe the GraphQL Doctor bot can bake in support for GraphQL Schema Linter, but for now it's a two-stop shop.

Google's "API Linter"

Google is doing some pretty interesting work in the API space. They were one of the first big players in the API space consistently explaining "Sometimes you want REST, sometimes you want RPC", and they're keeping at it with a general tool that works for gRPC and HTTP-in-general too. API linter operates on the protobuf surface layer, but can be set up to work with HTTP endpoints:

When using protocol buffers, each RPC must define the HTTP method and path using the google.api.http annotation:

rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books/*"
    body: "book"
  };
}

message CreateBookRequest {
  // The publisher who will publish this book.
  // When using HTTP/JSON, this field is automatically populated based
  // on the URI, because of the `{parent=publishers/*}` syntax.
  string parent = 1;

  // The book to create.
  // When using HTTP/JSON, this field is populated based on the HTTP body,
  // because of the `body: "book"` syntax.
  Book book = 2;

  // The user-specified ID for the book.
  // When using HTTP/JSON, this field is populated based on a query string
  // argument, such as `?book_id=foo`. This is the fallback for fields that
  // are not included in either the URI or the body.
  string book_id = 3;
}

The core ruleset for API Linter is rather impressive, and focuses a lot on awkward bits in the HTTP specification which are a bit unclear. Like, should GET have a body? The answer is a very squishy kinda maybe it can, but probably don't, depends on the tool you are building, ugh. Help.

Google decided to just answer that with: nope.

They also decided to persuade teams upgrade from proto2 to proto3.

Rule Ideas

You can automate pretty much anything with this stuff, and I've been thinking a lot
of rules that go beyond the common use cases of enforcing naming or pluralization.

Security

Ban HTTP Basic entirely
Make sure every endpoint has some sort of security (OAuth 2, API Key, but not both)
Every response should support application/vnd.api+json (JSON:API) not just plain-old JSON
ID's as integers let people crawl your API incredibly easily, switch to UUID

Errors

Your 20X response seems to have errors in it, why do you hate your consumers
There are no URLs in your errors, how can anyone find out more information about what went wrong
Error format should be RFC 7807

Versioning

Keep version numbers out of the URL
Version numbers in headers please
Ban all versioning and demand evolution (prepare for battle)

Many of these rules are HTTP API specific but you get the idea. Over time I'll be working on some of these and adding them to OpenAPI Contrib's Style Guide, and if you'd like to contribute I'll be happy to guide you through the process over on GitHub.

Summary

If you've heard the term API Governance, this is pretty much what most people are talking about. Currently a lot of the people trying to do governance are eyeballing API descriptions on every single PR, and training people to memorize all the quality rules they've come up with.

Manual API training is a thankless, inefficient, never-ending task, and it can be replaced (or drastically streamlined) with a linter baked into an editor, git hook, CI pipeline, GitHub Action, or a bot.

Don't waste customers time forcing them to try and figure out your inconsistencies. Don't waste all API developers time learning to memorizing style guides. Don't waste the API governance teams time reviewing APIs manually. Don't waste everyone's time fixing inconsistencies in production later.

API Design-First vs Code First

Phil Sturgeon — Thu, 24 Oct 2019 01:28:54 +0000

Should you do “API Design-first” or “code-first”, and what do these things even mean?

Continue reading on APIs You Won't Hate »

Server-Side Validation with API Descriptions

Phil Sturgeon — Mon, 27 May 2019 12:31:44 +0000

Validation can mean a lot of things, but in API land it generally means figuring out if the data being set to the API is any good or not. Validation can happen in a lot of different places, it can happen on the server, and it can happen in the client. Traditionally client-side and server-side validation have both played a role, covering different use-cases.

Client-side validation is generally used to very quickly provide feedback to a user, to do things like highlighting the input box that failed, with red outlines, tooltips explaining that the email address doesn’t look valid, explaining that the “Amount to pay off your credit card” should be higher than 0, etc. These days browsers take care of a lot of the visual feedback so often client-side validation is not doing quite as much as it used to, but it is still required for “either field A or B should be set, but not both, and if B is set, we C should be too.” sorts of thing.

Server-side validation has always been required and for an API is the most important of the two. An API that relies entirely on the client is going to end up with problems. Data coming from the client can never be trusted because it’s impossible for the server to know what happened on the client. Even if you’re developing a private API for only two known clients, there are always chances that validation in those clients breaks down; or someone will hit those APIs with curl or Postman and send some invalid stuff. Even if the database catches invalid data, the errors won’t be useful.

Writing validation rules has always been a major source of pains in my… neck, for the last 15 years, so an approach to syncing the two has forever been on my mind.

API Description Documents

Server-side validation is usually doing the most mundane of tasks.

Is this property required
Is this property an email address
Is this property a credit card number
Is this property required if other property is present

Some frameworks shove this logic in the controller, which is a pain when you need to validate the same payload in two different use cases. Others shove it in the data model, like Ruby on Rails:

Doesn’t this all sound incredibly familiar? This is exactly what API description docs (also known as specifications) are talking about, required, types, formats, etc… all of this is already handled for us entirely by the same API descriptions we used to generate our mock servers for trial integrations, that we wrote to get beautiful reference docs, that we are using to manage our API Gateway, etc.

Some of you may have read our article a while back about using JSON Schema for client-side validation, and now we want to show you how to leverage your existing source of truth for drastically reducing the amount of validation code you need to write server-side too.

Which Description Format

OpenAPI and JSON Schema are the two biggest API description formats, and there are a lot of options for all the programming languages.

OpenAPI tools are listed on OpenAPI.Tools and JSON Schema has a whole huge list on JSON Schema: Implementations.

JSON Schema Example

JSON Schema is not aware of metadata like URLs or HTTP methods as its designed to work with any JSON data instance. In API land the JSON data instance we’re most likely to work with is the HTTP request body or the response body.

For example purposes we are gonna make some JSON Schema validation happen in Node.js, but you can use any language that has a JSON Schema Validator (which is most of them).

To use JSON Schema for server-side validation, you normally just grab one of the validators, shove it in your controller, or “routing” or whatever your language/framework of choice calls it. Using Express.js, we can put this logic in our route.

A fairly familiar app.js to Node users, we are just requiring a few bits of code, and loading the userSchema.

That userSchema file comes from schemas/user.json which you can make locally, and will have contents like this:

When you inspect the structure, you can infer that our JSON object has the following list of properties: name, email, and date_of_birth. The first two are strings, and the third is a date. Also, name is marked as required.

Now we can run this Node app with node app.js and fire HTTP requests at it:

$ http -v PUT http://localhost:3000/123 name=Frank

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 14
Content-Type: text/html; charset=utf-8
Date: Sat, 25 May 2019 08:09:10 GMT
ETag: W/"e-4o7E1rWH1O+7xJOCXIMFqIbMSxE"
X-Powered-By: Express

that was great

Ok it liked that because name was set but email and date_of_birth are optional. Let's try sending them, but bad.

$ http -v PUT http://localhost:3000/123 name=Frank email=notanemail

HTTP/1.1 400 Bad Request
Connection: keep-alive
Content-Length: 164
Content-Type: application/json; charset=utf-8
X-Powered-By: Express

{
 "errors": [
 {
 "dataPath": ".email",
 "keyword": "format",
 "message": "should match format \"email\"",
 "params": {
 "format": "email"
 },
 "schemaPath": "#/properties/email/format"
 }
 ]
}

Oh no! Some errors happened. Sorry!

These errors are not the best format because we just dumped them out for demo purposes, but this can be tidied up with a simple helper.

If you were already doing validation in the controller, then your controller should be a lot cleaner, and if you are doing extensive validation in your model then this will remove a lot of the cruft. If you did not have validation before, then using this approach means you don’t need to start writing it. Win win win!

Also, whilst this works in any language, Ruby folks using Rack (therefore anyone using Rails too) can use committee, a fantastic middleware for making this a bit easier.

JSON Schema is pretty good at handling request body validation, but having to put this in every controller can be a bit annoying. OpenAPI can help us out here.

OpenAPI Middleware Example

OpenAPI can be a bit easier to implement here, due to it covering the service model too, not just the data model.

openapi: "3.0.0"
# ... snip ...
paths:
 /pets:
 post:
 description: Creates a new pet in the store
 operationId: addPet
 requestBody:
 description: Pet to add to the store
 required: true
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/NewPet'
 responses:
 '200':
 description: pet response
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/Pet'

Seeing as OpenAPI will say “this schema should be used for this combination or HTTP Method and Path” you do not need to provide the glue. Instead, many languages offer tools that let you just register a middleware, tell that middleware which OpenAPI file to use, then job done.

Sticking with Node/Express for the examples, let’s take a look at using OpenAPI and registering a middleware:

Tadaaa! You don’t have to put the validation checks in all the routes, because the middleware can handle that for you, and your route/controller code won’t even bother getting invoked if the request coming in is invalid. The framework middleware is able to look at the request, compare it to the API descriptions, and reject it with an error format (hopefully something like RFC 7807) before your code even needs to wake up.

There are a decent number of options out there, but there should be more:

For OpenAPI v3.0:

PHP: openapi-psr7-validator
Node.js: express-swagger-ajv-validator / express-openapi-validate
Ruby/Rails: committee
Perl: Mojolicious::Plugin::OpenAPI

For OpenAPI v2.0:

Rails: swagger_shield

The Rails tool swagger_shield is great. It wins maximum “Wont Hate Points” for using RFC 7807 on failure:

{
 "errors": [
 {
 "status": "422",
 "detail": "The property '#/widget/price' of type string did not match the following type: integer",
 "source": {
 "pointer": "#/widget/price"
 }
 }
 ]
}

Some Validation Still Required

This is only going to handle validation rules which do not require looking in a data store, or need some other sort of programming to run. You can do rather a lot with JSON Schema or OpenAPI, but it cannot tell you if the email address is valid, or if this resource is generally in the right state to be doing the thing you are trying to do.

Not a problem. You can still perform your own checks after this validation is done, and because everything is all using RFC 7807 the whole way through then your code and the middleware and everything else will all match. Lovely!

Testing Benefits

There are two huge benefits we have not quite got to yet, beyond the time and money saved from not having to write out a bunch of validation code.

The whole idea of trying to keep docs in sync with code goes out the window when your description documents are literally code.

Seeing as you are using the same description documents to handle request validation that you are using for your documentation, mock server, etc, there is no need for extra logic to ensure your requests are correctly described (or documented). You can just do your usual integration testing on requests, and you are all set.

expect(goodApple).to.be.jsonSchema(fruitSchema);

Your test suite handling bog standard unit and integration tests are now proving your documented requests are correct, and if somebody changes how requests work without updating the description docs, they’ve been caught in the act and their pull requests will fail. If they update the description in the pull request to fix the tests, boom, we can now have a little chat about why they just tried to commit a breaking change…! 🧐

Using description docs for validations only covers requests, so use the API description document to power contract testing to make sure responses are good too.

Tricking Colleagues into Writing Documentation via Contract Testing

Future of Server-Side Validation

This is a very old concept which has recently picked up steam as more developers catch onto the API Design-first workflow.

One of the benefits of writing HTTP APIs is that you usually are not locked into a single implementation, and do not have to try and force the “one size fits all” tooling that comes with it. Sadly that means some of the tools for some of the languages aren’t as excellent as others, but as we are a community of open-source developers we can fix that.

I’ve heard developers say “this is not performant” but there is no reason to believe that. A specific tool might not be written the most efficient way, but that can be fixed with PRs. So long as the tool is not parsing the entire document on the fly, and on startup constructs some sort of artifacts in memory, this could easily be more performant than running whatever behemoth of a “validation library” you’ve loaded up to do all this manually.

Another approach is to skip out on doing it in the server-side, and move it up a level: to the API Gateway. We’ll be writing more about that soon, but most API gateways are starting to get smarter about how they accept API descriptions as input, and how they use that input.

One example is Express Gateway, who added JSON Schema Validation, a project maintained by my friend and Stoplight.io colleague Vincenzo Chianese.

Summary

The days of treating descriptions like some annoying thing you have to do later to get docs are long behind us. API descriptions now come first, are used for contract testing, getting feedback on implementation, and a whole bunch of other stuff.

Use this as another carrot to convince your laggard teammates or boss that this is the way to go.