Streamlined Geek Talk

922 views

Published on

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

Published in: Technology, News & Politics
  • Be the first to comment

  • Be the first to like this

Streamlined Geek Talk

  1. 1. Streamlined Geek Talk Web Services APIs and Always Up-to-Date Documentation with Rails and Cucumber by Sarah Allen and Wolfram Arnold
  2. 2. multiple clients, multiple developers
  3. 3. Use cases • Corporate teams – communication between developers – outsourced development – documenting an open API • Open source – documenting API – interface stability
  4. 4. Always up-to-date Documentation spec = test = doc
  5. 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. 6. How we made it happen • Pre-existing codebase • Generate HTTP traffic logs from client apps • Wrote cucumber features for each use case
  7. 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. 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. 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. 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. 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. 12. Results Surfaces undocumented requirements Highlights use of undocumented API’s Software works well
  13. 13. Always up-to-date Documentation spec = test = doc Wolfram Arnold Sarah Allen rubyfocus.biz ultrasaurus.com www.mightyverse.com

×