Web Services APIs and Always Up-to-Date Documentationwith Rails and Cucumber by Sarah Allen and Wolfram Arnold

1. Streamlined Geek Talk
Web Services APIs and
Always Up-to-Date Documentation
with Rails and Cucumber
by Sarah Allen and Wolfram Arnold

2. multiple clients, multiple developers

3. Use cases
• Corporate teams
– communication between developers
– outsourced development
– documenting an open API
• Open source
– documenting API
– interface stability

4. Always up-to-date Documentation
spec = test = doc

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

6. How we made it happen
• Pre-existing codebase
• Generate HTTP traffic logs from client apps
• Wrote cucumber features for each use case

7. 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

8. 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

9. 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

10. 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"

11. 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

12. Results
Surfaces undocumented requirements
Highlights use of undocumented API’s
Software works well

13. Always up-to-date Documentation
spec = test = doc
Wolfram Arnold Sarah Allen
rubyfocus.biz ultrasaurus.com
www.mightyverse.com