Applying Twitter's API "Best Practices" In A ColdFusion Application

1. Ben Nadel

   

   • Chief Software Engineer, Epicenter Consulting
   • Author of The Blog of Ben Nadel (www.bennadel.com)
   • Adobe Community Profession
   • Adobe Certified ColdFusion Developer
   • Co-Manager New York ColdFusion User Group
   • ColdFusion, XHTML, CSS, jQuery Developer

2. How I Programmed A Lot Of Years Ago

   • ColdFusion back-end
   • Static front-end
   • Some DHTML
   • Mostly every request returned HTML
   • All code on a single server

3. How I Programmed A Few Years Ago

   • ColdFusion back-end
   • Minorly dynamic front-end: Sack.js
   • Mostly every request returned HTML
   • Comsuming a few e-commerce web-service calls:
     • Payment gateways
     • Shipping estimates

4. How I Programmed Not So Long Ago

   • ColdFusion back-end
   • Finally... jQuery - progressive enhancement
     • Some JSON
   • Still, most requests returned HTML
   • Consuming more 3rd party web services:
     • Email campaigns
     • Compliance Services
     • "Screen scraping"
     • Payment gateways
     • Shipping estimates

5. How I Program Now (And In The Future??)

   • ColdFusion back-end / half "API"
   • Much thicker client font-end
   • Half requests return HTML, half JSON
   • Finally exposing minor 3rd party API functionality

6. So, What Do I Know About API Architecture?

   • Not much!
   • But, I know ColdFusion pretty well

7. Learning By Immitation: Twitter

   • That Twitter, it's so hot right now!
   • Rank #11 on Alexa.com
   • Learn from the outside-in
   • Lots of internal mystery / flexability

8. WWTD: What Would Twitter Do?

   • RESTful URL architecture
   • Basic authentication
   • Multi-format responses
   • Meaningful status code usage
   • Duplicate-post protection
   • Rate limiting

9. REST: Representational State Transfer

   • Revolves around unique "resources"
   • Uses verbs: GET POST PUT DELETE
   • Hides underlying technology
   • Path fully describes resource
   • URL parameters describe resource display
   • Examples:
     • GET: /products/123456
     • GET: /categories
     • DELETE: /products/123456

10. Basic Authentication

    • Base64 encoding of "Username:Password"
    • Server response:
      • HTTP/1.0 401 Authorization Required
      • WWW-Authenticate: Basic realm="Secure Area"
    • Client response:
      • Authorization: Basic dHJpY2lhOm5hdWdodHk=
    • Base64 encoding is not secure

11. Multi-format Responses

    • Response is a representation of the resource
    • Different resources support different formats
    • Examples:
      • GET: /products/1234.json
      • GET: /products/1234.xml
      • GET: /products/1234?format=json

12. Meaningful Status Codes

    • 200 - OK
    • 400s all caused by user interaction
    • 400 - Bad Request
    • 401 - Unauthorized
    • 403 - Forbidden
    • 404 - Not Found
    • 405 - Method Not Allowed
    • 406 - Not Acceptable

13. Duplicate-Post Protection

    • Prevents two successive identical posts
    • Returns previous post

14. Rate Limiting

    • Limits the number of API requests
    • 400 Bad Request - GET Limit
    • 403 Forbidden - POST Limit
    • Insightful headers:
      • X-RateLimit-Limit
      • X-RateLimit-Remaining
      • X-RateLimit-Reset

15. Monkey See, Monkey Do

    
    

    View Demo

16. Task Demo API Outline

    • Tasks
      • GET: /tasks/get/{ID}.{FORMAT}
      • POST: /tasks/save.{FORMAT}
      • POST: /tasks/delete.{FORMAT}
    • Lists
      • GET: /lists.{FORMAT}
      • GET: /lists/{NAME}/tasks.{FORMAT}

17. API Request Life Cycle

    
    

18. You're In The Danger Zone!

    • There's a lot that can go wrong!
    • Every error requires a unique and meaningful response
    • Heavy use of CFTry, CFCatch, and CFThrow

19. CFTry / CFCatch / CFThrow

    
    

20. Let's Take A Look At Some Code

    
    

21. Closing Thoughts

    • CFM vs. CFC
    • Verb support
    • POST with CFHTTP / CFHTTPParam

22. Thank You For Listening

    • Ben Nadel
    • Blog: http://www.bennadel.com
    • Email: ben@bennadel.com
    • Ask Ben: http://www.bennadel.com/ask-ben
    • Consulting: http://www.epicenterconsulting.com