Upgrade to Pro — share decks privately, control downloads, hide ads and more …

REST API's: Easier Than You Imagined

Adam Tuttle
May 17, 2013
Technology
1
53

REST API's: Easier Than You Imagined

Taffy has changed a fair amount, and for the better, since its release 2.5 years ago. It's also now used in production on Adobe ColdFusion and Railo every day of the year. It's baked into Slatwall, the open source eCommerce plugin for Mura. It's used by an augmented reality iPhone application to send data and photos between phones and servers.

And still, it's the easiest, fastest way to get the job done from a CFML platform; and I'd like to help you get started writing API's today.

This session will teach you the basics of REST, as well as everything you need to know to get started writing REST API's with Taffy. From "what's an HTTP verb?" to Dependency Injection, to Uploading Files, and everywhere in between. We'll also cover adding an API to an existing application because as we all know, starting from scratch is not often a privilege of which we get the pleasure.

Adam Tuttle

May 17, 2013
Tweet

More Decks by Adam Tuttle

See All by Adam Tuttle
Errors are Best When Emailed... Said Nobody Ever
atuttle
0
1.5k

Other Decks in Technology

See All in Technology
Introduction to Works of ML Engineer in LY Corporation
lycorp_recruit_jp
0
110
いざ、BSC討伐の旅
nikinusu
2
780
第1回 国土交通省 データコンペ参加者向け勉強会③ - Snowflake x estie編 -
estie
0
130
CysharpのOSS群から見るModern C#の現在地
neuecc
2
3.2k
[CV勉強会@関東 ECCV2024 読み会] オンラインマッピング x トラッキング MapTracker: Tracking with Strided Memory Fusion for Consistent Vector HD Mapping (Chen+, ECCV24)
abemii
0
220
Taming you application's environments
salaboy
0
190
複雑なState管理からの脱却
sansantech
PRO
1
140
TypeScriptの次なる大進化なるか！？　条件型を返り値とする関数の型推論
uhyo
2
1.6k
Making your applications cross-environment - OSCG 2024 NA
salaboy
0
190
Why does continuous profiling matter to developers? #appdevelopercon
salaboy
0
190
エンジニア人生の拡張性を高める 「探索型キャリア設計」の提案
tenshoku_draft
1
120
Can We Measure Developer Productivity?
ewolff
1
150

Featured

See All Featured
Why Our Code Smells
bkeepers
PRO
334
57k
CoffeeScript is Beautiful & I Never Want to Write Plain JavaScript Again
sstephenson
159
15k
Product Roadmaps are Hard
iamctodd
PRO
49
11k
Refactoring Trust on Your Teams (GOTO; Chicago 2020)
rmw
31
2.7k
The Power of CSS Pseudo Elements
geoffreycrofte
73
5.3k
The Art of Programming - Codeland 2020
erikaheidi
52
13k
Design and Strategy: How to Deal with People Who Don’t "Get" Design
morganepeng
126
18k
How to Ace a Technical Interview
jacobian
276
23k
Faster Mobile Websites
deanohume
305
30k
Performance Is Good for Brains [We Love Speed 2024]
tammyeverts
6
410
StorybookのUI Testing Handbookを読んだ
zakiyama
27
5.3k
The World Runs on Bad Software
bkeepers
PRO
65
11k

Transcript

  1. REST API’s: Easier Than You Imagined @AdamTuttle FusionGrokker.com You are

    here

  2. Agenda • REST 101 • Creating REST APIs with ColdFusion*

    • Adding an API to an existing app • Best Practices, Patterns, Anti-patterns

  3. Agenda • REST 101 • Creating REST APIs with ColdFusion*

    • Adding an API to an existing app • Best Practices, Patterns, Anti-patterns *Using Taffy
  4. None

  5. I’m @AdamTuttle

  6. That’s Me!

  7. I make stuff

  8. • Created May 2010 • #6 most watched ColdFusion project

    on GitHub • 8+ people contributing • Syntax doesn’t suck I made Taffy

  9. Who Uses Taffy?

  10. REST 101

  11. What is REST?

  12. What is REST?

  13. Request Response GET http://... Headers Request data 200 OK Headers

    Response data
  14. None

  15. <form action=”http://...” method=”POST”> </form>

  16. Vocabulary Verb Noun Data Format (“Mime Type”) Data

  17. HTTP Verbs GET Read POST Insert PUT Update DELETE Delete

    OPTIONS Allowed Verbs HEAD Headers Only

  18. HTTP Verbs GET Read POST Insert PUT Update DELETE Delete

    OPTIONS Allowed Verbs HEAD Headers Only Safe Unsafe Idempotent

  19. HTTP Nouns •google.com/ •goodreads.com/books/Earnest-Cline/ Ready-Player-One •cfobjective.com/sessions/rest-apis-easier- than-you-imagined/

  20. <form action=”http://...” method=”POST”> </form>

  21. <form action=”http://...” method=”POST”> </form> Noun

  22. <form action=”http://...” method=”POST”> </form> Noun Verb

  23. <form action=”http://...” method=”POST”> </form> Noun Verb <input type=”hidden” name=”foo” value=”bar”

    /> Request Data

  24. Data Format HTML: text/html Image: image/jpeg JSON: application/json XML: application/xml

    ZIP: application/octet-stream

  25. HTTP Status Codes • 2xx = Success • 3xx =

    Redirect • 4xx = Client Error • 5xx = Server Error

  26. Do Not Write This Down This will not be on

    the test

  27. Raw Request $ telnet www.google.com 80 Trying 173.194.73.104... Connected to

    www.google.com. Escape character is '^]'. GET /index.html HTTP/1.1 Host: www.google.com {blank line}

  28. Raw Response HTTP/1.1 200 OK Date: Sat, 11 May 2013

    18:29:45 GMT [...] X-XSS-Protection: 1; mode=block X-Frame-Options: SAMEORIGIN Transfer-Encoding: chunked <!doctype html><html.......... }Response Headers

  29. Web APIs work similarly

  30. Raw Request POST /api/v1/tweets HTTP/1.1 Host: twitter.com Content-Type: application/json Accept:

    application/json, */*;q=0.9 User-Agent: MyTwitterApp { “username”: “AdamTuttle”, “tweet”: “Hello, #CFObjective!” } [blank line]

  31. Raw Response HTTP/1.1 201 Tweet Created Content-Type: application/json; charset=UTF-8 {

    ... }

  32. <form action=”http://.../foo/bar” method=”POST”> </form> <input type=”hidden” name=”foo” value=”bar” />

  33. POST /....../foo/bar Host: www.example.com Content-Type: x-www-form-urlencoded Accept: application/json foo=bar&flap=jacks

  34. POST /....../foo/bar Host: www.example.com Content-Type: x-www-form-urlencoded Accept: application/json foo=bar&flap=jacks No

    question mark

  35. Creating REST APIs with ColdFusion* *Using Taffy

  36. Choices • Taffy • Mach-II • ColdBox • Relaxation •

    Powernap • RestfulCF • CF10

  37. Why I (still) <3 Taffy • Simplest, Most-concise syntax •

    Easily extended (security layer, etc) • Doesn’t require access to CFAdmin • Portable (Railo, CF8+ supported) • Plays fine with any app framework • ONLY Convention-over-Config option (CF10?) • Open Source

  38. Your First Taffy-powered API

  39. Application.cfc component extends=”taffy.core.api” {} index.cfm <!--- this space intentionally blank

    --->
  40. None

  41. An API w/ Results ... that fits into a Tweet

  42. Application.cfc component extends=”taffy.core.api”{} index.cfm resources/hi.cfc component extends = ”taffy.core.resource” taffy_uri

    = ”/hi” { function get(){ return representationOf(“hi”); } }

  43. Application.cfc component extends=”taffy.core.api”{} index.cfm resources/hi.cfc component extends = ”taffy.core.resource” taffy_uri

    = ”/hi” { function get(){ return representationOf(“hi”); } } 36 104
  44. None
  45. None
  46. None
  47. None
  48. None

  49. Anatomy of an API

  50. Anatomy of an API Application.cfc index.cfm /resources/...

  51. Application.cfc component extends=”taffy.core.api” { variables.framework = {}; function applicationStartEvent(){} function

    requestStartEvent(){} function onTaffyRequest(){} }

  52. index.cfm

  53. Resources • Live in /resources subfolder • Each resource defines

    its own URI • Only implemented verbs are allowed • Collections vs. Members

  54. Resources component extends=”taffy.core.resource” taffy_uri=”/foo/{fooId}” { public function get(fooId){} public function

    delete(fooId){} }

  55. 3 Data Input Options

  56. Tokens & Query Params • Mapped by name to method

    args • Tokens are the same for every method in a resource CFC and always required (otherwise 404) • Query Params are optional; also passed by name

  57. Simple Input component extends=”taffy.core.resource” taffy_uri=”/foo/{fooId}” { function get(fooId, optional string

    city){ //... } } <cfargument name=”city” required=”false” /> /api/index.cfm/foo/17?city=Philadelphia

  58. Simple Input component extends=”taffy.core.resource” taffy_uri=”/foo/{fooId}” { function get(fooId, optional string

    city){ //... } } <cfargument name=”city” required=”false” /> /api/index.cfm/foo/17?city=Philadelphia

  59. Simple Input component extends=”taffy.core.resource” taffy_uri=”/foo/{fooId}” { function get(fooId, optional string

    city){ //... } } <cfargument name=”city” required=”false” /> /api/index.cfm/foo/17?city=Philadelphia

  60. Simple Input component extends=”taffy.core.resource” taffy_uri=”/foo/{fooId}” { function get(fooId, optional string

    city){ //... } } <cfargument name=”city” required=”false” /> /api/index.cfm/foo/17?city=Philadelphia

  61. Simple Input component extends=”taffy.core.resource” taffy_uri=”/foo/{fooId}” { function get(fooId, optional string

    city){ //... } } <cfargument name=”city” required=”false” /> /api/index.cfm/foo/17?city=Philadelphia

  62. Request Body Input Taffy Supports JSON and Form-encoded bodies as

    long as you set the Content-Type header {“foo”:”bar baz”,”baz”:true} foo=bar%20baz&baz=true

  63. Data Output

  64. Returning Data representationOf method abstracts serialization component extends=”taffy.core.resource” taffy_uri=”/foo” {

    public function get(){ var querySvc = new Query(); //... return representationOf( someQuery ); } }

  65. Returning Data representationOf method abstracts serialization component extends=”taffy.core.resource” taffy_uri=”/foo” {

    public function get(){ var querySvc = new Query(); //... return representationOf( myStruct ); } }

  66. Returning Data representationOf method abstracts serialization component extends=”taffy.core.resource” taffy_uri=”/foo” {

    public function get(){ var querySvc = new Query(); //... return representationOf( myArray ); } }

  67. ColdFusion serializes queries ... abnormally. {"COLUMNS":["COL1","COL2","COL3"], "DATA":[[3,3,true]]} Taffy’s queryToArray() helper

    converts queries to an array of structures [ {"CoL1":3,"col2":3,"col3":true}, {"CoL1":4,"col2":4,"col3":false} ] queryToArray()

  68. queryToArray() return representationOf( queryToArray( myQuery ) );

  69. Response Headers return representationOf( ... ).withStatus( 201, “Created” ).withHeaders( {

    “X-MY-HEADER” = “My header value” } );

  70. Empty Success return noData().withStatus(201, “Created”); return noData();

  71. More Advanced github.com/atuttle/Taffy/wiki

  72. Dependency Injection /resources/FooService.cfc /resources/FooCollection.cfc component { function doStuff(){...}; } component

    extends=”taffy.core.resource” ...{ property name=”FooService”; function get(){ local.foo = this.FooService.doStuff(); //... } }

  73. Resource Subfolders /resources/fooCollection.cfc “fooCollection” /resources/Cat/Grumpy.cfc “CatGrumpy” /resources/Services/Old/User.cfc “ServicesOldUser” Bean Name

    Generation

  74. • Custom Token Regex • Intercept requests w/ onTaffyRequest •

    3rd Party Bean Factories • Verb:Method mapping w/ metadata • Custom result serializers • Environment specific config • ETags for result caching • ... much, much, much more

  75. Adding an API to an existing App

  76. Shared State • Subfolder supported, not required • Enable by

    using the same Application Name • Shared variables* *with great power comes great responsibility

  77. Best Practices

  78. Separate Collections & Members

  79. Version your API from day 1. /api/v1/foo/bar

  80. Thoughtful URIs

  81. Human-Readable URIs

  82. Token vs Query String

  83. PUT or POST?

  84. HATEOAS

  85. HTTP Status Codes are your friend

  86. Antipatterns

  87. I hate you. If you code like this...

  88. GET request writes data

  89. 2+ requests / task

  90. 200 Error

  91. Using Cookies

  92. Getting Support Mailing List: bit.ly/taffy-users IRC: #coldfusion on freenode and

    dalnet Tweet me: @AdamTuttle

  93. Thank You

  94. None