Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

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

433 views

Published on

Learn how to automatically test your API's documentation by using API Blueprints and dredd.

Presented at API Days Australia on February 28, 2017.

Published in: Software
  • Be the first to comment

  • Be the first to like this

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

  1. 1. Automatic testing of (RESTful) API documentation API Days Australia, February 2017 By Rouven Weßling ( ) Ecosystem Developer / Developer Evangelist, Contentful @RouvenWessling photo credit: bySydney Harbour Bridge, Australia Lenny K Photography (CC-BY)
  2. 2. A content management developer platform with an API at its core.
  3. 3. What do you do?
  4. 4. Powered by
  5. 5. A new look.
  6. 6. Documentation will be wrong
  7. 7. Users hate that
  8. 8. It's all in the spec api blueprint A powerful high-level API description language for web APIs.
  9. 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. 10. Let's get testing DREDD No more outdated API documentation.
  11. 11. Testing read-only node_modules/.bin/dredd cma.apib https://api.contentful.com -m GET
  12. 12. 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
  13. 13. Hooks node_modules/.bin/dredd cma.apib https://api.contentful.com --hookfiles=./test-hooks.js -m GET
  14. 14. Skipping Tests var hooks = require('hooks'); hooks.before( "Webhook calls > Webhook call details > Get the webhook call details", function (transaction) { transaction.skip = true; });
  15. 15. Mutating data var hooks = require('hooks'); hooks.before( "Entries > Delete an Entry", function (transaction) { client.createEntry(entry, "1234") });
  16. 16. Rate limiting var hooks = require('hooks'); const DELAY = 1000/6.0; hooks.afterEach(function(transaction, done) { setTimeout(done, DELAY); });
  17. 17. Changing request data var hooks = require('hooks'); hooks.beforeEach(function (transaction, done) { transaction.fullPath = transaction.fullPath.replace('fp91oelsziea', 'gbkxklvmolc1'); done(); });
  18. 18. 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(); });
  19. 19. Security
  20. 20. 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(); });
  21. 21. CI the beast
  22. 22. Conclusion Base your documentation on an API spec Test that spec Make it part of your CI Don't substitute your integration tests
  23. 23. Slides available on Slideshare: http://www.slideshare.net/rwessling/ Follow me on Twitter: @RouvenWessling
  24. 24. Meetup Thursday, March 2, 2017 7:00 pm Pivotal Labs, Level 11, 155 Clarence Street, Sydney https://www.meetup.com/Contentful-User-Meetup-Sydney/events/237520492/

×