Hapi-Swagger Gotchas

wilfred@eastpole.nl — Sun, 10 Nov 2019 15:09:45 +0000

I am currently working on an API and I'm using Hapi to make sure my endpoints are validated without too much trouble, and to make sure I'm getting a properly documented API in Swagger for (almost) free.

Now, the good news is: there is not a lot that I need to do in order to have an API that is documented quite properly. The bad news is, instead of having to understand Swagger, you now have to understand all the Hapi incantations to get Swagger output in the way you want it.

There are a couple of things I ran into that I'm sure I will have forgotten the next time I get to it, so I will post a note here. In some of these cases, it required some digging around to understand how to get it to work properly, so hopefully, by posting it here, you don't have to.

Producing either JSON or a text stream

Hapi already allows you to document to validations for the response of your endpoint. Unfortunately, that only works in case your response is an object. So what do you do if your endpoint can both produce a JSON object, as well as a plain text stream? In that case, you might not care too much about the validations, but having the JSON version documented might still be useful.

In that case, rather than documenting your response as a Joi schema in the validate section of your endpoint configuration, you might consider relying on Hapi-Swagger's mechanism for documenting responses.

So rather than doing this:

options: {
  validate: {
    response: Joi.object().keys(...)
  }
}

You would do this:

options: {
  'hapi-swagger': {
    responses: {
      200: {
        schema: Joi.object().keys(...)
      }
    }
  }
}

Labels

If your endpoints are returning JSON and if you define the structure of your JSON with Joi validations, either using the validate key or the hapi-swagger.responses.200.schema key of your definition, then you might want to consider adding labels to all of your Joi.object()s. Without it, hapi-swagger will automatically label the 'models', which will render your documentation pretty much unreadable.

Markdown

This might be a surprise, but Swagger descriptions are supporting Markdown. I suggest you use it. It helps to add a little bit more structure to your documentation.

Security

If you don't provide unauthorized access to your endpoints, then it helps including information on how to authenticate in your swagger.json file. I found the Hapi-Swagger documentation a little dense on how to do it. It turns out you will have to do two things:

In the general plugin options of your Hapi-Swagger configuration, you will have to add a securityDefinitions option:

options: {
  securityDefinitions: {
    'API Key': {
      type: 'apiKey',    // apiKey is defined by the Swagger spec
      name: 'apiKey',    // the name of the query parameter / header
      in: 'query'        // how the key is passed
    }
  }

The next thing you need to do is add an option to the route configuration of every route that requires authentication:

options: {
  'hapi-swagger': {
    security: [{ 'API Key': {} }]
  }
}

Note that the key in your security definitions and the key in your route options need to correspond.

If you add it this way, then the Swagger UI will include an «Authorize» button at the top of your API description, allowing you to set the API key for all further invocations. You can also click the little lock in all the endpoints. That will bring up the same dialog.

Now, bear in mind that adding this does not guarantee that your API is also protected against unauthorized access. It just guarantees that Swagger understands the need for an API key. You will still have to add an authentication scheme to your Hapi server, and include it in the auth key of your route configuration.

If you do that, and if you use a query param based API key, then you might find that your query param validations no longer work. After all, you are now all of a sudden passing in an additional apiKey parameter, that your endpoint itself is completely unaware of.

There are two ways to solve it: either you change the Joi object associated with the query key of your route definition to include unknowns, or you remove the apiKey in the lifecycle hook of your authentication scheme. (I did the latter.)

Redis Async Generators

wilfred@eastpole.nl — Mon, 01 Jul 2019 15:51:21 +0000

If you have never gone through Joshua Bloch's API Design in Bumper Stickers presentation, then you certainly should. Here are four of the guidelines he's suggesting:

APIs should be easy to use and hard to misuse.

When in Rome, do as the Romans do.

APIs should be self-documenting

Don't make the client do anything the library could do.

It sounds so obvious. However, I don't have to think too deep to come up with examples of APIs that clearly miss the mark.

To be fair, "easy to use" is a little vague. "Easy to use" might mean that it requires very little code to use the API. But it could also mean that the code you do have to write is idiomatic for the language in which you're coding. Or perhaps it should be easy to read, without even knowing the library.

Scala's Dispatch library is an example of a library that optimized for compactness of the calling code instead of readability. And with Scala's flexible syntax, nobody even knew for sure what "idiomatic" really meant in Scala's world.

JavaScript is different. It's syntax is less flexible than Scala's. It doesn't allow you to "extend" the syntax and make it behave as something else. You have to live with whatever it has baked in. As a consequence, I would expect JavaScript libraries to converge more quickly towards an idiomatic and common way of doing things.

So, moving on to Redis. Redis is — in a way — a foreign entity in JavaScript. It's API wasn't designed with JavaScript in mind in particular. It seems that some of that spilled over in its client binding. A lot of things would be much simpler if the standard redis library for node would be based on promises rather than callbacks. I'd say promises and async await constructs are the more idiomatic way to do things these days.

The same goes for iterators. If you have code that iterates over a collection, then Redis' JavaScript API makes that quite painful. That is, it requires quite some careful control by the caller. It violates not just one but all of four of the above guidelines from Josh Bloch's talk.

This is a slightly modified version of some code I found on StackOverflow to iterate over all keys matching the pattern person*.

let cursor = '0'
let redisClient = …
function scan (pattern, callback) {

  redisClient.scan(cursor, 'MATCH', pattern, 'COUNT', '1000', function (err, reply) {
    if(err){
        throw err
    }
    cursor = reply[0]
    if(cursor !== '0') {
        let keys = reply[1]
        keys.forEach(callback)
        return scan(pattern,callback)
    }
  })
}

scan('person*', console.info);

I found this code hard to digest. You need to understand about ‘0’ being the magic marker to mark the end of the matching values. That not only feels not all that idiomatic, but it also forces me to control a whole bunch of things I’d rather leave to the API instead.

So therefore, I present to you redis-async-gen — async generators for Redis. That’s quite a mouthful, but the important thing is that it compacts this code considerably, that it’s easier on the eyes, and that it relieves the caller from having to carefully manage a cursor: