Streamlined Geek Talk Web Services APIs and

Always Up-to-Date Documentation

with Rails and Cucumber

by Sarah Allen and Wolfram Arnold

multiple clients, multiple developers

Use cases

• Corporate teams– communication between developers– outsourced development– documenting an open API

• Open source– documenting API– interface stability

Always up-to-date Documentation

spec = test = doc

Server Engineerwrites code

Server Engineerwrites code

CI Pass?Client Engineerwrites code

Client Engineerwrites code

Server Engineerwrites scenarioServer Engineerwrites scenario

Covered?

Feature DocsFeature Docs

New Client App Legacy Code

Target Workflow

How we made it happen

• Pre-existing codebase• Generate HTTP traffic logs from client apps• Wrote cucumber features for each use case

Tools• Cucumber BDD framework – http://cukes.info/– http://wiki.github.com/aslakhellesoy/cucumber

• Webrat (gem)• Using DB fixtures in cucumber– http://wiki.github.com/aslakhellesoy/cucumber/fixtures

• Using XML fixtures to compare server response– xmlsubsetmatcher library

• Continuous integration – hudson, cruisecontrol.rb, integrity

• Example:– http://github.com/mightyverse/cucumber_xml

Rails Web Services

app/controllers/projects_controller.rb

respond_to do |format| format.html

# views/projects/index.html.erb format.xml

# views/projects/index.xml.builderend

Rails Web Servicesapp/views/projects/index.xml.builder

xml.instruct!xml.projects do xml.total @projects.length @projects.each do |project| xml.project do xml.name project.name xml.notes project.notes end endend

Feature Scenarios

Feature: Project XML API In order to read project data data As a device or client application using the XML REST interface I want to make GET requests to the /projects URL

Scenario: Get Medium When I send an XML GET to /projects.xml Then I get a 200 (success) status result And the response header Content-Type matches application/xml And the response should be a superset of the file: "xml/projects.xml"

Workflow

• Publish doc from source repository• Continuous integration run feature scenarios

on every checkin• All engineers have access to CI• Separate test and production environments

Results

Surfaces undocumented requirements

Highlights use of undocumented API’s

Software works well

Always up-to-date Documentation

spec = test = doc

www.mightyverse.com

Wolfram Arnold rubyfocus.biz

Sarah Allenultrasaurus.com