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
エンジニアのキャリアをちょっと楽しくする3本の軸/Three Pillars to Make an Engineer's Career More Enjoyable
kwappa
1
2.8k
Python と Snowflake はズッ友だょ！~ Snowflake の Python 関連機能をふりかえる ~
__allllllllez__
2
140
推しは推せるときに推せ！ プロダクトにフィードバックしていこう
nakasho
0
440
Google Cloud Next '24 Recap(Cloud Run/k8s)
mokocm
0
290
Cypress or Playwright?
rainerhahnekamp
0
150
私が trocco を推す理由
__allllllllez__
2
290
Kernel MemoryでAzure OpenAI Serviceとお手軽データソース連携
mitsuzono
1
270
ゼロから始めるVue.jsコミュニティ貢献 / first-vuejs-community-contribution-link-and-motivation
lmi
1
140
.NET Profiler in 2024.
kkamegawa
2
610
VS CodeでAWSを操作しよう
smt7174
9
1.9k
Handling focus in 2024
tahia910
0
120
データベース02: データベースの概念
trycycle
0
170

Featured

See All Featured
Happy Clients
brianwarren
92
6.4k
Web development in the modern age
philhawksworth
203
10k
Reflections from 52 weeks, 52 projects
jeffersonlam
345
19k
Building Flexible Design Systems
yeseniaperezcruz
320
37k
Unsuck your backbone
ammeep
663
57k
How To Stay Up To Date on Web Technology
chriscoyier
782
250k
Statistics for Hackers
jakevdp
790
220k
What's new in Ruby 2.0
geeforr
337
31k
How GitHub (no longer) Works
holman
305
140k
The Pragmatic Product Professional
lauravandoore
26
5.8k
4 Signs Your Business is Dying
shpigford
176
21k
I Don’t Have Time: Getting Over the Fear to Launch Your Podcast
jcasabona
22
1.6k

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