SlideShare a Scribd company logo
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.
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
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
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

What's hot

Automate that
Automate thatAutomate that
Automate that
Atlassian
 
AWS SDK for PHP のインストールから 始めるクラウドマスターへの道 〜 Promise による非同期オペレーション 〜
AWS SDK for PHP のインストールから 始めるクラウドマスターへの道 〜 Promise による非同期オペレーション 〜 AWS SDK for PHP のインストールから 始めるクラウドマスターへの道 〜 Promise による非同期オペレーション 〜
AWS SDK for PHP のインストールから 始めるクラウドマスターへの道 〜 Promise による非同期オペレーション 〜
崇之 清水
 

What's hot (20)

Building a Serverless company with Node.js, React and the Serverless Framewor...
Building a Serverless company with Node.js, React and the Serverless Framewor...Building a Serverless company with Node.js, React and the Serverless Framewor...
Building a Serverless company with Node.js, React and the Serverless Framewor...
 
Java 8 concurrency abstractions
Java 8 concurrency abstractionsJava 8 concurrency abstractions
Java 8 concurrency abstractions
 
Building a chatbot – step by step
Building a chatbot – step by stepBuilding a chatbot – step by step
Building a chatbot – step by step
 
Automate that
Automate thatAutomate that
Automate that
 
Server Side Swift
Server Side SwiftServer Side Swift
Server Side Swift
 
Distributed Eventing in OSGi
Distributed Eventing in OSGiDistributed Eventing in OSGi
Distributed Eventing in OSGi
 
Gatling @ Scala.Io 2013
Gatling @ Scala.Io 2013Gatling @ Scala.Io 2013
Gatling @ Scala.Io 2013
 
WordPress RESTful API & Amazon API Gateway (English version)
WordPress RESTful API & Amazon API Gateway (English version)WordPress RESTful API & Amazon API Gateway (English version)
WordPress RESTful API & Amazon API Gateway (English version)
 
2016 - Easing Your Way Into Docker: Lessons From a Journey to Production
2016 - Easing Your Way Into Docker: Lessons From a Journey to Production2016 - Easing Your Way Into Docker: Lessons From a Journey to Production
2016 - Easing Your Way Into Docker: Lessons From a Journey to Production
 
Maarten Balliauw "Indexing and searching NuGet.org with Azure Functions and S...
Maarten Balliauw "Indexing and searching NuGet.org with Azure Functions and S...Maarten Balliauw "Indexing and searching NuGet.org with Azure Functions and S...
Maarten Balliauw "Indexing and searching NuGet.org with Azure Functions and S...
 
Karate - powerful and simple framework for REST API automation testing
Karate - powerful and simple framework for REST API automation testingKarate - powerful and simple framework for REST API automation testing
Karate - powerful and simple framework for REST API automation testing
 
Building domain-specific testing tools : lessons learned from the Apache Slin...
Building domain-specific testing tools : lessons learned from the Apache Slin...Building domain-specific testing tools : lessons learned from the Apache Slin...
Building domain-specific testing tools : lessons learned from the Apache Slin...
 
Azure Durable Functions
Azure Durable FunctionsAzure Durable Functions
Azure Durable Functions
 
Reflection in Pharo: Beyond Smalltak
Reflection in Pharo: Beyond SmalltakReflection in Pharo: Beyond Smalltak
Reflection in Pharo: Beyond Smalltak
 
Indexing and searching NuGet.org with Azure Functions and Search - .NET fwday...
Indexing and searching NuGet.org with Azure Functions and Search - .NET fwday...Indexing and searching NuGet.org with Azure Functions and Search - .NET fwday...
Indexing and searching NuGet.org with Azure Functions and Search - .NET fwday...
 
AWS SDK for PHP のインストールから 始めるクラウドマスターへの道 〜 Promise による非同期オペレーション 〜
AWS SDK for PHP のインストールから 始めるクラウドマスターへの道 〜 Promise による非同期オペレーション 〜 AWS SDK for PHP のインストールから 始めるクラウドマスターへの道 〜 Promise による非同期オペレーション 〜
AWS SDK for PHP のインストールから 始めるクラウドマスターへの道 〜 Promise による非同期オペレーション 〜
 
The Works 2018 - Software Track - Development 101: Build Using API and Overvi...
The Works 2018 - Software Track - Development 101: Build Using API and Overvi...The Works 2018 - Software Track - Development 101: Build Using API and Overvi...
The Works 2018 - Software Track - Development 101: Build Using API and Overvi...
 
State in stateless serverless functions
State in stateless serverless functionsState in stateless serverless functions
State in stateless serverless functions
 
Server Side Swift - AppBuilders 2017
Server Side Swift - AppBuilders 2017Server Side Swift - AppBuilders 2017
Server Side Swift - AppBuilders 2017
 
Serverless Angular, Material, Firebase and Google Cloud applications
Serverless Angular, Material, Firebase and Google Cloud applicationsServerless Angular, Material, Firebase and Google Cloud applications
Serverless Angular, Material, Firebase and Google Cloud applications
 

Viewers also liked

HCLT Whitepaper: Multi- Tenancy on Private Cloud
HCLT Whitepaper: Multi- Tenancy on Private CloudHCLT Whitepaper: Multi- Tenancy on Private Cloud
HCLT Whitepaper: Multi- Tenancy on Private Cloud
HCL Technologies
 
In sight telepsychiatry competitor profiles tracey fu
In sight telepsychiatry competitor profiles tracey fuIn sight telepsychiatry competitor profiles tracey fu
In sight telepsychiatry competitor profiles tracey fu
traceyxfu
 
Plaquette Commerciale Phone Contact
Plaquette Commerciale Phone ContactPlaquette Commerciale Phone Contact
Plaquette Commerciale Phone Contact
phonecontact
 
Canada Digital Future 2014
Canada Digital Future 2014Canada Digital Future 2014
Canada Digital Future 2014
Counselorauto
 
Dynamic clouds and networks without infrastructure
Dynamic clouds and networks without infrastructureDynamic clouds and networks without infrastructure
Dynamic clouds and networks without infrastructure
University of Hertfordshire
 

Viewers also liked (20)

php[world] 2016 - API Mashup - Combining APIs for Fun and Profit
php[world] 2016 - API Mashup - Combining APIs for Fun and Profitphp[world] 2016 - API Mashup - Combining APIs for Fun and Profit
php[world] 2016 - API Mashup - Combining APIs for Fun and Profit
 
Adapting our API for multiple platforms
Adapting our API for multiple platformsAdapting our API for multiple platforms
Adapting our API for multiple platforms
 
HCLT Whitepaper: Multi- Tenancy on Private Cloud
HCLT Whitepaper: Multi- Tenancy on Private CloudHCLT Whitepaper: Multi- Tenancy on Private Cloud
HCLT Whitepaper: Multi- Tenancy on Private Cloud
 
In sight telepsychiatry competitor profiles tracey fu
In sight telepsychiatry competitor profiles tracey fuIn sight telepsychiatry competitor profiles tracey fu
In sight telepsychiatry competitor profiles tracey fu
 
Qy stainless steel self priming gas-liquid mixing pump
Qy stainless steel self priming gas-liquid mixing pumpQy stainless steel self priming gas-liquid mixing pump
Qy stainless steel self priming gas-liquid mixing pump
 
Best Practices for API Adoption
Best Practices for API AdoptionBest Practices for API Adoption
Best Practices for API Adoption
 
A RESTful API for Controlling Dynamic Streaming Topologies
A RESTful API for Controlling Dynamic Streaming TopologiesA RESTful API for Controlling Dynamic Streaming Topologies
A RESTful API for Controlling Dynamic Streaming Topologies
 
Charity Business Automation
Charity Business AutomationCharity Business Automation
Charity Business Automation
 
SITB15 - Qu'est qu'une Data Driven Company à l'heure de la digitalisation ?
SITB15 - Qu'est qu'une Data Driven Company à l'heure de la digitalisation ?SITB15 - Qu'est qu'une Data Driven Company à l'heure de la digitalisation ?
SITB15 - Qu'est qu'une Data Driven Company à l'heure de la digitalisation ?
 
USF Mid East and Turkey Pitch
USF Mid East and Turkey PitchUSF Mid East and Turkey Pitch
USF Mid East and Turkey Pitch
 
Plaquette Commerciale Phone Contact
Plaquette Commerciale Phone ContactPlaquette Commerciale Phone Contact
Plaquette Commerciale Phone Contact
 
Structure 2014 - The future of cloud computing survey results
Structure 2014 - The future of cloud computing survey resultsStructure 2014 - The future of cloud computing survey results
Structure 2014 - The future of cloud computing survey results
 
Canada Digital Future 2014
Canada Digital Future 2014Canada Digital Future 2014
Canada Digital Future 2014
 
Sales Hacker Conference San Francisco - Jason Lemkin - The 10 Key Revenue Mis...
Sales Hacker Conference San Francisco - Jason Lemkin - The 10 Key Revenue Mis...Sales Hacker Conference San Francisco - Jason Lemkin - The 10 Key Revenue Mis...
Sales Hacker Conference San Francisco - Jason Lemkin - The 10 Key Revenue Mis...
 
Education and Training for The Future Workforce
Education and Training for The Future WorkforceEducation and Training for The Future Workforce
Education and Training for The Future Workforce
 
Dynamic clouds and networks without infrastructure
Dynamic clouds and networks without infrastructureDynamic clouds and networks without infrastructure
Dynamic clouds and networks without infrastructure
 
APIs and Innovation
APIs and InnovationAPIs and Innovation
APIs and Innovation
 
China air conditioner market report
China air conditioner market reportChina air conditioner market report
China air conditioner market report
 
Ripening of a RESTful API
Ripening of a RESTful APIRipening of a RESTful API
Ripening of a RESTful API
 
Integrated Customer Service Maximization Experience Vision Demonstrator
Integrated Customer Service Maximization Experience Vision DemonstratorIntegrated Customer Service Maximization Experience Vision Demonstrator
Integrated Customer Service Maximization Experience Vision Demonstrator
 

Similar to Nordic APIs - Automatic Testing of (RESTful) API Documentation

CouchDB on Android
CouchDB on AndroidCouchDB on Android
CouchDB on Android
Sven Haiges
 
Intro to node and mongodb 1
Intro to node and mongodb   1Intro to node and mongodb   1
Intro to node and mongodb 1
Mohammad Qureshi
 

Similar to Nordic APIs - Automatic Testing of (RESTful) API Documentation (20)

API Days Paris - Automatic Testing of (RESTful) API Documentation
API Days Paris - Automatic Testing of (RESTful) API DocumentationAPI Days Paris - Automatic Testing of (RESTful) API Documentation
API Days Paris - Automatic Testing of (RESTful) API Documentation
 
Full stack development with node and NoSQL - All Things Open - October 2017
Full stack development with node and NoSQL - All Things Open - October 2017Full stack development with node and NoSQL - All Things Open - October 2017
Full stack development with node and NoSQL - All Things Open - October 2017
 
Full Stack Development with Node.js and NoSQL
Full Stack Development with Node.js and NoSQLFull Stack Development with Node.js and NoSQL
Full Stack Development with Node.js and NoSQL
 
Crafting Evolvable Api Responses
Crafting Evolvable Api ResponsesCrafting Evolvable Api Responses
Crafting Evolvable Api Responses
 
Building Better Web APIs with Rails
Building Better Web APIs with RailsBuilding Better Web APIs with Rails
Building Better Web APIs with Rails
 
Externalizing Authorization in Micro Services world
Externalizing Authorization in Micro Services worldExternalizing Authorization in Micro Services world
Externalizing Authorization in Micro Services world
 
IVS CTO Night And Day 2018 Winter - [re:Cap] Serverless & Mobile
IVS CTO Night And Day 2018 Winter - [re:Cap] Serverless & MobileIVS CTO Night And Day 2018 Winter - [re:Cap] Serverless & Mobile
IVS CTO Night And Day 2018 Winter - [re:Cap] Serverless & Mobile
 
Velocity EU 2014 — Offline-first web apps
Velocity EU 2014 — Offline-first web appsVelocity EU 2014 — Offline-first web apps
Velocity EU 2014 — Offline-first web apps
 
Rethinking Syncing at AltConf 2019
Rethinking Syncing at AltConf 2019Rethinking Syncing at AltConf 2019
Rethinking Syncing at AltConf 2019
 
Sharding and Load Balancing in Scala - Twitter's Finagle
Sharding and Load Balancing in Scala - Twitter's FinagleSharding and Load Balancing in Scala - Twitter's Finagle
Sharding and Load Balancing in Scala - Twitter's Finagle
 
Use Windows Azure Service Bus, BizTalk Services, Mobile Services, and BizTalk...
Use Windows Azure Service Bus, BizTalk Services, Mobile Services, and BizTalk...Use Windows Azure Service Bus, BizTalk Services, Mobile Services, and BizTalk...
Use Windows Azure Service Bus, BizTalk Services, Mobile Services, and BizTalk...
 
Saving Time And Effort With QuickBase Api - Sergio Haro
Saving Time And Effort With QuickBase Api - Sergio HaroSaving Time And Effort With QuickBase Api - Sergio Haro
Saving Time And Effort With QuickBase Api - Sergio Haro
 
Prairie DevCon 2015 - Crafting Evolvable API Responses
Prairie DevCon 2015 - Crafting Evolvable API ResponsesPrairie DevCon 2015 - Crafting Evolvable API Responses
Prairie DevCon 2015 - Crafting Evolvable API Responses
 
Open stack ocata summit enabling aws lambda-like functionality with openstac...
Open stack ocata summit  enabling aws lambda-like functionality with openstac...Open stack ocata summit  enabling aws lambda-like functionality with openstac...
Open stack ocata summit enabling aws lambda-like functionality with openstac...
 
Play Framework: async I/O with Java and Scala
Play Framework: async I/O with Java and ScalaPlay Framework: async I/O with Java and Scala
Play Framework: async I/O with Java and Scala
 
Introduction to the SharePoint Client Object Model and REST API
Introduction to the SharePoint Client Object Model and REST APIIntroduction to the SharePoint Client Object Model and REST API
Introduction to the SharePoint Client Object Model and REST API
 
Intro to Node
Intro to NodeIntro to Node
Intro to Node
 
OneRing @ OSCamp 2010
OneRing @ OSCamp 2010OneRing @ OSCamp 2010
OneRing @ OSCamp 2010
 
CouchDB on Android
CouchDB on AndroidCouchDB on Android
CouchDB on Android
 
Intro to node and mongodb 1
Intro to node and mongodb   1Intro to node and mongodb   1
Intro to node and mongodb 1
 

More from Rouven Weßling

More from Rouven Weßling (6)

PHPcon Poland - Static Analysis of PHP Code – How the Heck did I write so man...
PHPcon Poland - Static Analysis of PHP Code – How the Heck did I write so man...PHPcon Poland - Static Analysis of PHP Code – How the Heck did I write so man...
PHPcon Poland - Static Analysis of PHP Code – How the Heck did I write so man...
 
API World 2016 - API Mashup - Combining for Fun and Profit
API World 2016 - API Mashup - Combining for Fun and ProfitAPI World 2016 - API Mashup - Combining for Fun and Profit
API World 2016 - API Mashup - Combining for Fun and Profit
 
vienna.html - Turn your Blog into Facebook Instant Articles + Contentful Intro
vienna.html - Turn your Blog into Facebook Instant Articles + Contentful Introvienna.html - Turn your Blog into Facebook Instant Articles + Contentful Intro
vienna.html - Turn your Blog into Facebook Instant Articles + Contentful Intro
 
Static Analysis of PHP Code – IPC Berlin 2016
Static Analysis of PHP Code – IPC Berlin 2016Static Analysis of PHP Code – IPC Berlin 2016
Static Analysis of PHP Code – IPC Berlin 2016
 
What is the Joomla Framework and why do we need it?
What is the Joomla Framework and why do we need it?What is the Joomla Framework and why do we need it?
What is the Joomla Framework and why do we need it?
 
Joomla Day DK 2012
Joomla Day DK 2012Joomla Day DK 2012
Joomla Day DK 2012
 

Recently uploaded

Recently uploaded (20)

5 Reasons Driving Warehouse Management Systems Demand
5 Reasons Driving Warehouse Management Systems Demand5 Reasons Driving Warehouse Management Systems Demand
5 Reasons Driving Warehouse Management Systems Demand
 
INGKA DIGITAL: Linked Metadata by Design
INGKA DIGITAL: Linked Metadata by DesignINGKA DIGITAL: Linked Metadata by Design
INGKA DIGITAL: Linked Metadata by Design
 
10 Essential Software Testing Tools You Need to Know About.pdf
10 Essential Software Testing Tools You Need to Know About.pdf10 Essential Software Testing Tools You Need to Know About.pdf
10 Essential Software Testing Tools You Need to Know About.pdf
 
Secure Software Ecosystem Teqnation 2024
Secure Software Ecosystem Teqnation 2024Secure Software Ecosystem Teqnation 2024
Secure Software Ecosystem Teqnation 2024
 
OpenChain @ LF Japan Executive Briefing - May 2024
OpenChain @ LF Japan Executive Briefing - May 2024OpenChain @ LF Japan Executive Briefing - May 2024
OpenChain @ LF Japan Executive Briefing - May 2024
 
A Guideline to Zendesk to Re:amaze Data Migration
A Guideline to Zendesk to Re:amaze Data MigrationA Guideline to Zendesk to Re:amaze Data Migration
A Guideline to Zendesk to Re:amaze Data Migration
 
Abortion ^Clinic ^%[+971588192166''] Abortion Pill Al Ain (?@?) Abortion Pill...
Abortion ^Clinic ^%[+971588192166''] Abortion Pill Al Ain (?@?) Abortion Pill...Abortion ^Clinic ^%[+971588192166''] Abortion Pill Al Ain (?@?) Abortion Pill...
Abortion ^Clinic ^%[+971588192166''] Abortion Pill Al Ain (?@?) Abortion Pill...
 
TROUBLESHOOTING 9 TYPES OF OUTOFMEMORYERROR
TROUBLESHOOTING 9 TYPES OF OUTOFMEMORYERRORTROUBLESHOOTING 9 TYPES OF OUTOFMEMORYERROR
TROUBLESHOOTING 9 TYPES OF OUTOFMEMORYERROR
 
The Impact of PLM Software on Fashion Production
The Impact of PLM Software on Fashion ProductionThe Impact of PLM Software on Fashion Production
The Impact of PLM Software on Fashion Production
 
GraphSummit Stockholm - Neo4j - Knowledge Graphs and Product Updates
GraphSummit Stockholm - Neo4j - Knowledge Graphs and Product UpdatesGraphSummit Stockholm - Neo4j - Knowledge Graphs and Product Updates
GraphSummit Stockholm - Neo4j - Knowledge Graphs and Product Updates
 
A Python-based approach to data loading in TM1 - Using Airflow as an ETL for TM1
A Python-based approach to data loading in TM1 - Using Airflow as an ETL for TM1A Python-based approach to data loading in TM1 - Using Airflow as an ETL for TM1
A Python-based approach to data loading in TM1 - Using Airflow as an ETL for TM1
 
A Comprehensive Appium Guide for Hybrid App Automation Testing.pdf
A Comprehensive Appium Guide for Hybrid App Automation Testing.pdfA Comprehensive Appium Guide for Hybrid App Automation Testing.pdf
A Comprehensive Appium Guide for Hybrid App Automation Testing.pdf
 
How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?
How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?
How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?
 
Advanced Flow Concepts Every Developer Should Know
Advanced Flow Concepts Every Developer Should KnowAdvanced Flow Concepts Every Developer Should Know
Advanced Flow Concepts Every Developer Should Know
 
KLARNA - Language Models and Knowledge Graphs: A Systems Approach
KLARNA -  Language Models and Knowledge Graphs: A Systems ApproachKLARNA -  Language Models and Knowledge Graphs: A Systems Approach
KLARNA - Language Models and Knowledge Graphs: A Systems Approach
 
Studiovity film pre-production and screenwriting software
Studiovity film pre-production and screenwriting softwareStudiovity film pre-production and screenwriting software
Studiovity film pre-production and screenwriting software
 
Crafting the Perfect Measurement Sheet with PLM Integration
Crafting the Perfect Measurement Sheet with PLM IntegrationCrafting the Perfect Measurement Sheet with PLM Integration
Crafting the Perfect Measurement Sheet with PLM Integration
 
Breaking the Code : A Guide to WhatsApp Business API.pdf
Breaking the Code : A Guide to WhatsApp Business API.pdfBreaking the Code : A Guide to WhatsApp Business API.pdf
Breaking the Code : A Guide to WhatsApp Business API.pdf
 
Microsoft 365 Copilot; An AI tool changing the world of work _PDF.pdf
Microsoft 365 Copilot; An AI tool changing the world of work _PDF.pdfMicrosoft 365 Copilot; An AI tool changing the world of work _PDF.pdf
Microsoft 365 Copilot; An AI tool changing the world of work _PDF.pdf
 
CompTIA Security+ (Study Notes) for cs.pdf
CompTIA Security+ (Study Notes) for cs.pdfCompTIA Security+ (Study Notes) for cs.pdf
CompTIA Security+ (Study Notes) for cs.pdf
 

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.
  • 3.
  • 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
  • 12.
  • 13.
  • 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(); });
  • 24.
  • 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