SlideShare a Scribd company logo

Nordic APIs - Automatic Testing of (RESTful) API Documentation

•
•
Rouven Weßling
Rouven Weßling

Learn how to automatically test your API's documentation by using API Blueprints and dredd. Presented at the Nordic APIs Platform Summit on October 25, 2016

1 of 26
Download to read offline
Automatic testing of (RESTful) API documentation Nordic APIs Platform Summit, October 2016 By Rouven Weßling ( ) Ecosystem Developer / Developer Evangelist, Contentful @RouvenWessling photo credit: byStockholm, Approaching Blue Hour Tobias Lindman (CC-BY)
A content management developer platform with an API at its core.
Nordic APIs - 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
Nordic APIs - Automatic Testing of (RESTful) API Documentation
Nordic APIs - Automatic Testing of (RESTful) API Documentation
Hooks beforeAllcalled at the beginning of the whole test run beforeEachcalled before each HTTP transaction beforecalled before some specific HTTP transaction beforeEachValidationcalled before each HTTP transaction is validated beforeValidationcalled before some specific HTTP transaction is validated aftercalled a er some specific HTTP transaction regardless its result afterEachcalled a er each HTTP transaction afterAllcalled 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
Nordic APIs - 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/nordic- apis-automatic-testing-of-restful-api-documentation Follow me on Twitter: @RouvenWessling

More Related Content

Nordic APIs - Automatic Testing of (RESTful) API Documentation

  • 1. Automatic testing of (RESTful) API documentation Nordic APIs Platform Summit, October 2016 By Rouven Weßling ( ) Ecosystem Developer / Developer Evangelist, Contentful @RouvenWessling photo credit: byStockholm, Approaching Blue Hour Tobias Lindman (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 beforeAllcalled at the beginning of the whole test run beforeEachcalled before each HTTP transaction beforecalled before some specific HTTP transaction beforeEachValidationcalled before each HTTP transaction is validated beforeValidationcalled before some specific HTTP transaction is validated aftercalled a er some specific HTTP transaction regardless its result afterEachcalled a er each HTTP transaction afterAllcalled 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/nordic- apis-automatic-testing-of-restful-api-documentation Follow me on Twitter: @RouvenWessling