Automating testing, documentation and validation with JSON schema in hapi

[ptte]

At bloglovin, we have started building services on top of hapi, which is a beautiful framework.

One of the things we wanted to achieve however was to automatically generate documentation for our different endpoints/services.

Starting with a routes file we realized that we we're missing more information about the incoming and outgoing data, and we did not see how we could get there with JOI.

By writing schemas in json/yaml, we allow for the whole range of validation structures that's supported by the JSON schema standard. It also makes it possible to add meta data around the data we're describing, so as to make automatic documentation of endpoints more elaborate, and easier.

We have also worked with allowing validation of outgoing data, so as to be able to automate/heavily simplify (turns out it's really hard to fully automate the creation of the tests) integration testing. This also really improves the documentation abilities.

On top of this, we support versioning of schemas, which is useful if you want to have multiple versions of an api running at the same time.

An example of a schema (not used in production).

id: PROJECT://schemas/search/requests/create-user-1.0.0
$schema: "http://json-schema.org/draft-03/schema#"
definitions:
  path:
    type: object
    additionalProperties: false
    properties:
      id:
        type: number
        description: The id of the user to create.
  payload:
    type: object
    additionalProperties: false
    properties:
      name:
        type: string
        description: A users full name
        required: true
      username:
        type: string
        description: "Username for user, A-z only"
        required: true
      avatar:
        type: boolean
        description: We want to know if a user has an avatar or not
        required: true
      location:
        type: string
        description: "Simple comma separated string of locations (Stockholm, Sweden)"
        required: true
      about:
        type: string
        description: The users description
        required: true

[hueniverse]

Hey @ptte can you rework the title and abstract to make is clear this is a different talk from the one @reid is planning #117

[ptte]

@hueniverse I've updated the description and title. Hope it's a bit more clear.

Does accepted mean that I should plan to go to oakland? :)

[mikeal]

yes ;)

[hueniverse]

Close due to speak change in availability.