api days paris - automatic testing of (restful) api documentation
TRANSCRIPT
![Page 1: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/1.jpg)
Automatic testing of(RESTful) API documentation
API Days Paris, December 2016
By Rouven Weßling ( )Ecosystem Developer / Developer Evangelist, Contentful
@RouvenWessling
photo credit: by Musée du Louvre Dustin Gaffke (CC-BY)
![Page 2: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/2.jpg)
A content management developer platform with an API at its core.
![Page 3: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/3.jpg)
![Page 4: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/4.jpg)
What do you do?
![Page 5: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/5.jpg)
Powered by
![Page 6: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/6.jpg)
Documentation will be wrong
![Page 7: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/7.jpg)
Users hate that
![Page 8: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/8.jpg)
It's all in the spec
api blueprintA powerful high-level API description language for web APIs.
![Page 9: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/9.jpg)
## 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",
![Page 10: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/10.jpg)
Let's get testing
DREDDNo more outdated API documentation.
![Page 11: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/11.jpg)
Testing read-onlynode_modules/.bin/dredd cma.apib https://api.contentful.com \ -m GET
![Page 12: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/12.jpg)
![Page 13: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/13.jpg)
![Page 14: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/14.jpg)
HooksbeforeAll 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
![Page 15: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/15.jpg)
Hooksnode_modules/.bin/dredd cma.apib https://api.contentful.com \ --hookfiles=./test-hooks.js \ -m GET
![Page 16: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/16.jpg)
Skipping Testsvar hooks = require('hooks');
hooks.before( "Webhook calls > Webhook call details > Get the webhook call details", function (transaction) { transaction.skip = true; });
![Page 17: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/17.jpg)
Mutating datavar hooks = require('hooks');
hooks.before( "Entries > Delete an Entry", function (transaction) { client.createEntry(entry, "1234") });
![Page 18: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/18.jpg)
Rate limitingvar hooks = require('hooks'); const DELAY = 1000/6.0;
hooks.afterEach(function(transaction, done) { setTimeout(done, DELAY); });
![Page 19: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/19.jpg)
Changing request datavar hooks = require('hooks');
hooks.beforeEach(function (transaction, done) { transaction.fullPath = transaction.fullPath.replace('fp91oelsziea', 'gbkxklvmolc1');
done(); });
![Page 20: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/20.jpg)
Chai assertionsvar 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(); });
![Page 21: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/21.jpg)
Security �
![Page 22: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/22.jpg)
Censor private datavar 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(); });
![Page 23: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/23.jpg)
CI the beast
![Page 24: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/24.jpg)
![Page 25: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/25.jpg)
ConclusionBase your documentation on an API specTest that specMake it part of your CIDon't substitute your integration tests
![Page 26: API Days Paris - Automatic Testing of (RESTful) API Documentation](https://reader034.vdocuments.mx/reader034/viewer/2022042605/58714d961a28ab55588b71f3/html5/thumbnails/26.jpg)
Slides available on Slideshare: http://www.slideshare.net/rwessling/api-days-paris-automatic-testing-of-restful-api-documentation
Follow me on Twitter: @RouvenWessling