read

A new version of Dredd - the API Documentation testing tool from Apiary Inc. - has been released, and it has changed a few things for the better. During the upgrade at Ride I ran into a few problems, mostly based around how we had been using Dredd and API Blueprint.

I've blogged about Dredd and API Blueprint a few times, covering the concept and workflow, and later showing off more in-depth how you can structure your API Documentation. This is still the approach we use, and if you're not familiar with Dredd maybe head over to one of those.

v1.1.0 was released June 17th, and whilst it's not exactly a new iPhone or a driverless car, I'm excited. One of the main things they snuck in there is experimental support for Swagger! I've not had a play with that yet, but it's great that they're starting to support both, especially as Apiary supports Swagger too.

Nullable

One thing I noticed was support for the nullable. Adam Kliment - author of Dredd - created a hack hook to support nullable, but it was very much a workaround. We had to shove a #nullable at the end of the line.

- started_at: `2015-01-07T14:03:43Z` (string, nullable) - #nullable

Now - I think due to switching from Protagonist to Fury.js - we can remove the hook and the hacktag.

- started_at: `2015-01-07T14:03:43Z` (string, nullable)

Multiple Response Testing

The main thing I noticed, was that Dredd was now testing all multiple responses. Multiple responses look like this:

## Avatar collection [/avatars]

### Upload an avatar [POST]

+ Request (application/json; charset=utf-8)

    + Attributes
        - avatars (object)
          - avatar_url: `http://example.org/some-actual-file.jpg`

+ Response 201 (application/json; charset=utf-8)

    + Attributes
        - avatars (Avatar Full)

+ Response 415 (application/json; charset=utf-8)

    + Attributes
        - errors (array[Error Unsupported Media Type])

This was really common in our API, as a way to show that you might get an important error. We don't show every possible error sure, but if something seemed unique or interested it would go in.

Using previous versions of Dredd, if you had multiple responses, you would see the following:

warn: Runtime compilation warning: Multiple responses, using first.
 on Avatar > Avatar collection > Upload an avatar

Now, Dredd will give them all a go!

The downside to Dredd trying to run new tests is that it will probably break your build. Seeing as the request is built identically, the response will be identical, and the test will fail! Instead of getting a 415 here, we'll end up getting a 200.

To get around this I had to abandon multiple responses (boo!) and switch to using two request transactions, like this:

## Avatar collection [/avatars]

### Upload an avatar [POST]

+ Request OK (application/json; charset=utf-8)

    + Attributes
        - avatars (object)
          - avatar_url: `http://example.org/some-actual-file.jpg`

+ Response 201 (application/json; charset=utf-8)

    + Attributes
        - avatars (Avatar Full)

+ Request Unsupported Media Type (image/gif)

+ Response 415 (application/json; charset=utf-8)

    + Attributes
        - errors (array[Error Unsupported Media Type])

Notice here the first request now has a name, Request OK, which can be arbitrary string (within reason). I chose to stick to the HTTP status reason so it matches, as that seemed like as good a convention as any.

You'll also notice another change, I've added a new named request: Request Unsupported Media Type. That image/gif will trigger the API to respond with an error, as we only accept application/json, image/jpeg or image/png for that endpoint. Now that it is a new transaction it wont conflict with the OK test, and we're all green!

Thanks!

Great job from the Dredd contributors, I saw Honza Javorek's name show up a whole bunch in the changelog and know a lot of others put in serious effort too.


Book Cover

Build APIs You Won't Hate

Everyone and their dog wants an API, so you should probably learn how to build them.

Buy it from LeanPub or Amazon.

Image

Phil Sturgeon

Platform Engineer @ WeWork who talks about APIs a lot. Programming Polyglot, Pragmatist, Centerist and Sarcasist. Ex-The League of Extraordinary Packages, PHP The Right Way, Ex-PHP-FIG, Ex-CodeIgniter, Ex-FuelPHP, Ex-PyroCMS.

Back to Overview