SlideShare a Scribd company logo

API Days Paris - Automatic Testing of (RESTful) API Documentation

•
•
Rouven Weßling
Rouven Weßling

This document discusses automatically testing RESTful API documentation by: 1) Describing API Blueprint, a language for describing web API specifications that can be tested. 2) Introducing Dredd, a tool for testing API documentation against a live API. 3) Providing examples of using Dredd hooks to mutate data, add delays, and make assertions during testing.

1 of 26
Download to read offline
Automatic testing of (RESTful) API documentation API Days Paris, December 2016 By Rouven Weßling ( ) Ecosystem Developer / Developer Evangelist, Contentful @RouvenWessling photo credit: byMusée du Louvre Dustin Gaffke (CC-BY)
A content management developer platform with an API at its core.
API Days Paris - Automatic Testing of (RESTful) API Documentation
What do you do?
Powered by
Documentation will be wrong
Users hate that
It's all in the spec api blueprint A powerful high-level API description language for web APIs.
## Questions Collection [/questions] ### Create a New Question [POST] You may create your own question using this action. It takes a JSON object containing a question and a collection of answers in the form of choices. + Request (application/json) { "question": "Favourite programming language?", "choices": [ "Swift", "Python", "Objective-C", "Ruby" ] } + Response 201 (application/json) + Headers Location: /questions/2 + Body { "question": "Favourite programming language?", "published_at": "2015-08-05T08:40:51.620Z", "choices": [ { "choice": "Swift",
Let's get testing DREDD No more outdated API documentation.
Testing read-only node_modules/.bin/dredd cma.apib https://api.contentful.com -m GET
API Days Paris - Automatic Testing of (RESTful) API Documentation
API Days Paris - Automatic Testing of (RESTful) API Documentation
Hooks beforeAll called at the beginning of the whole test run beforeEach called before each HTTP transaction before called before some specific HTTP transaction beforeEachValidation called before each HTTP transaction is validated beforeValidation called before some specific HTTP transaction is validated after called a er some specific HTTP transaction regardless its result afterEach called a er each HTTP transaction afterAll called a er whole test run
Hooks node_modules/.bin/dredd cma.apib https://api.contentful.com --hookfiles=./test-hooks.js -m GET
Skipping Tests var hooks = require('hooks'); hooks.before( "Webhook calls > Webhook call details > Get the webhook call details", function (transaction) { transaction.skip = true; });
Mutating data var hooks = require('hooks'); hooks.before( "Entries > Delete an Entry", function (transaction) { client.createEntry(entry, "1234") });
Rate limiting var hooks = require('hooks'); const DELAY = 1000/6.0; hooks.afterEach(function(transaction, done) { setTimeout(done, DELAY); });
Changing request data var hooks = require('hooks'); hooks.beforeEach(function (transaction, done) { transaction.fullPath = transaction.fullPath.replace('fp91oelsziea', 'gbkxklvmolc1'); done(); });
Chai assertions var hooks = require('hooks'); var assert = require('chai').assert; hooks.afterEach(function(transaction, done) { if (!transaction.skip) { assert.match(transaction.real.headers['x-contentful-request-id'], /^content-api:[a-zA-Z0-9]{22}$/ } done(); });
Security
Censor private data var hooks = require('hooks'); const SECRET_HEADERS = ['Authorization'].map(header => header.toLowerCase()); hooks.afterEachValidation(function(transaction, done) { Object.keys(transaction.request.headers).forEach(function(key) { if (SECRET_HEADERS.indexOf(key.toLowerCase()) > -1) { transaction.request.headers[key] = "***HIDDEN SECRET DATA***"; } }); done(); });
CI the beast
API Days Paris - Automatic Testing of (RESTful) API Documentation
Conclusion Base your documentation on an API spec Test that spec Make it part of your CI Don't substitute your integration tests
Slides available on Slideshare: http://www.slideshare.net/rwessling/api-days- paris-automatic-testing-of-restful-api-documentation Follow me on Twitter: @RouvenWessling

More Related Content

API Days Paris - Automatic Testing of (RESTful) API Documentation

  • 1. Automatic testing of (RESTful) API documentation API Days Paris, December 2016 By Rouven Weßling ( ) Ecosystem Developer / Developer Evangelist, Contentful @RouvenWessling photo credit: byMusée du Louvre Dustin Gaffke (CC-BY)
  • 2. A content management developer platform with an API at its core.
  • 8. It's all in the spec api blueprint A powerful high-level API description language for web APIs.
  • 9. ## Questions Collection [/questions] ### Create a New Question [POST] You may create your own question using this action. It takes a JSON object containing a question and a collection of answers in the form of choices. + Request (application/json) { "question": "Favourite programming language?", "choices": [ "Swift", "Python", "Objective-C", "Ruby" ] } + Response 201 (application/json) + Headers Location: /questions/2 + Body { "question": "Favourite programming language?", "published_at": "2015-08-05T08:40:51.620Z", "choices": [ { "choice": "Swift",
  • 10. Let's get testing DREDD No more outdated API documentation.
  • 11. Testing read-only node_modules/.bin/dredd cma.apib https://api.contentful.com -m GET
  • 14. Hooks beforeAll called at the beginning of the whole test run beforeEach called before each HTTP transaction before called before some specific HTTP transaction beforeEachValidation called before each HTTP transaction is validated beforeValidation called before some specific HTTP transaction is validated after called a er some specific HTTP transaction regardless its result afterEach called a er each HTTP transaction afterAll called a er whole test run
  • 16. Skipping Tests var hooks = require('hooks'); hooks.before( "Webhook calls > Webhook call details > Get the webhook call details", function (transaction) { transaction.skip = true; });
  • 17. Mutating data var hooks = require('hooks'); hooks.before( "Entries > Delete an Entry", function (transaction) { client.createEntry(entry, "1234") });
  • 18. Rate limiting var hooks = require('hooks'); const DELAY = 1000/6.0; hooks.afterEach(function(transaction, done) { setTimeout(done, DELAY); });
  • 19. Changing request data var hooks = require('hooks'); hooks.beforeEach(function (transaction, done) { transaction.fullPath = transaction.fullPath.replace('fp91oelsziea', 'gbkxklvmolc1'); done(); });
  • 20. Chai assertions var hooks = require('hooks'); var assert = require('chai').assert; hooks.afterEach(function(transaction, done) { if (!transaction.skip) { assert.match(transaction.real.headers['x-contentful-request-id'], /^content-api:[a-zA-Z0-9]{22}$/ } done(); });
  • 22. Censor private data var hooks = require('hooks'); const SECRET_HEADERS = ['Authorization'].map(header => header.toLowerCase()); hooks.afterEachValidation(function(transaction, done) { Object.keys(transaction.request.headers).forEach(function(key) { if (SECRET_HEADERS.indexOf(key.toLowerCase()) > -1) { transaction.request.headers[key] = "***HIDDEN SECRET DATA***"; } }); done(); });
  • 25. Conclusion Base your documentation on an API spec Test that spec Make it part of your CI Don't substitute your integration tests
  • 26. Slides available on Slideshare: http://www.slideshare.net/rwessling/api-days- paris-automatic-testing-of-restful-api-documentation Follow me on Twitter: @RouvenWessling