Nordic APIs - Automatic Testing of (RESTful) API Documentation
0 likes239 views
The document discusses the importance of automatic testing for RESTful API documentation, emphasizing the use of API Blueprint for describing web APIs. It details various testing hooks and methods such as Dredd for ensuring updated documentation and validated API behavior. The conclusion encourages integrating specification testing into continuous integration processes to enhance documentation reliability.
![## 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",](https://image.slidesharecdn.com/nordicapis-automatictestingofrestfulapidocumentation-161025092535/85/Nordic-APIs-Automatic-Testing-of-RESTful-API-Documentation-9-320.jpg)
![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();
});](https://image.slidesharecdn.com/nordicapis-automatictestingofrestfulapidocumentation-161025092535/85/Nordic-APIs-Automatic-Testing-of-RESTful-API-Documentation-20-320.jpg)
![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();
});](https://image.slidesharecdn.com/nordicapis-automatictestingofrestfulapidocumentation-161025092535/85/Nordic-APIs-Automatic-Testing-of-RESTful-API-Documentation-22-320.jpg)
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.
- 4. What do you do?
- 5. Powered by
- 6. Documentation will be wrong
- 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
- 15. Hooks node_modules/.bin/dredd cma.apib https://api.contentful.com --hookfiles=./test-hooks.js -m GET
- 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(); });
- 21. Security
- 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(); });
- 23. CI the beast
- 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