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

Target Workflow
New Client App Legacy Code
Feature Docs
Server Engineer
Covered?
writes scenario
Client Engineer Server Engineer
CI Pass?
writes code writes code

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
r e s p o n d _ t o d o |f o r m a t |
f o r m a t .h t m l
# v ie w s / p r o je c t s / in d e x . h t m l . e r b
f o r m a t .x m l
# v ie w s / p r o je c t s / in d e x . x m l . b u ild e r
e nd

Rails Web Services
app/views/projects/index.xml.builder
x m l . in s t r u c t !
x m l . p r o je c t s d o
x m l . t o t a l @p r o je c t s . le n g t h
@p r o je c t s . e a c h d o |p r o je c t |
x m l . p r o je c t d o
x m l . n a m e p r o je c t . n a m e
x m l . n o t e s p r o je c t . n o t e s
e nd
e nd
e nd

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
Wolfram Arnold Sarah Allen
rubyfocus.biz ultrasaurus.com
www.mightyverse.com