The Most Basic API Contract

API Contracts can be Complicated

The OpenAPI contract allows us to collaborate and automate and automate a range different things, but first we have to build that contract. The contract itself has a fairly simple structure where we have metadata and have resources -- you know you can look through the specifications and you can go look at examples but unfortunately there are a lot of different examples, with a lot of different stuff shown in those examples, and then your brain starts to get overwhelmed by all the stuff you could be doing.

Because of all these confusing examples, I wanted to see if I could build just the simplest API contract that I could and this is it:

openapi: 3.0.0
info:
  title: This is the Title
  version: "1.0"
paths:
  /collections:
    get:
      summary: "This is a general, plain-language description of the path, or collection"
      responses:
        '200':    # status code
          description: "Some text about response code 200"

Now, I'm not saying this is truly an OpenAPI 3.0 compliant contract, but what I am saying is this is the minimal information that I would need to start sharing information about what I'm building. I have some basic metadata such as the version of the OpenAPI contract I'm trying to adhere to; this lets us know how to parse it and how it should be formatted. In the info section we should minimally give a title to the API and a version for this particular API we’re describing.

Then down in the paths portion we can start to describe those endpoints those resources those collections. First there’s the endpoint itself, then the verb, and details for responses grouped by response code. I also added a summary, which is probably a little more than I needed to do, but I want to render it and to be able to look at and be at least somewhat meaningful to my audience.

Now that I have a super basic contract, I can start to iterate and expand it. I probably want to add a schema that includes the actual response payload.  At a minimum you can return just a string. Of course, we don't usually just do a string, so if you want to describe your payload as a json object. Because we have the content defined as “application/json” when we add properties (in this case “id” and “someotherField”) they now show up in our renderer as an actual json payload.

The OpenAPI Contract isn’t about documentation, it's about iterating and improving.  We can convert the yaml document to json so it can be parsed by other tools that for automation such as running it through a linter. When we verify the document we start to see other things we need to do – just because it renders and looks pretty in a document viewer it still has things that need to be corrected to be a mature, robust API Contract.

The reason that we continue to grow and iterate that contract is so that we can share it with other people and other teams and collaborate and make something that just flows through the entire system. We’re not building a document, but truly a contract that tells people what we've promised, and through integration and automation delivers that promise.