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

Building an API with cffractal and ColdBox

Matt Gifford
November 08, 2018

Building an API with cffractal and ColdBox

Matt Gifford

November 08, 2018
Tweet

More Decks by Matt Gifford

Other Decks in Technology

Transcript

  1. @coldfumonkeh Matt Gifford Building an API with CFFRACTAL and COLDBOX

  2. None
  3. I API

  4. THE PLAN

  5. /api/v1/artists /api/v1/artists/:artistID /api/v1/albums /api/v1/albums/:albumID /api/v1/labels /api/v1/labels/:labelID

  6. GETTING STARTED

  7. THE CORE MODULE

  8. None
  9. > coldbox create app name = "music_api" installTestBox = true

    > install cborm cbvalidation --save
  10. > coldbox create module core Created /Users/monkehworks/music_api/modules_app/core Created /Users/monkehworks/music_api/modules_app/core/models Created

    /Users/monkehworks/music_api/modules_app/core/models/models_here.txt Created /Users/monkehworks/music_api/modules_app/core/ModuleConfig.cfc Created /Users/monkehworks/music_api/modules_app/core/views Created /Users/monkehworks/music_api/modules_app/core/views/home Created /Users/monkehworks/music_api/modules_app/core/views/home/index.cfm Created /Users/monkehworks/music_api/modules_app/core/handlers Created /Users/monkehworks/music_api/modules_app/core/handlers/Home.cfc
  11. > coldbox create module core Created /Users/monkehworks/music_api/modules_app/core Created /Users/monkehworks/music_api/modules_app/core/models Created

    /Users/monkehworks/music_api/modules_app/core/models/models_here.txt Created /Users/monkehworks/music_api/modules_app/core/ModuleConfig.cfc Created /Users/monkehworks/music_api/modules_app/core/views Created /Users/monkehworks/music_api/modules_app/core/views/home Created /Users/monkehworks/music_api/modules_app/core/views/home/index.cfm Created /Users/monkehworks/music_api/modules_app/core/handlers Created /Users/monkehworks/music_api/modules_app/core/handlers/Home.cfc
  12. modules_app core models services AlbumService.cfc ArtistService.cfc LabelService.cfc Album.cfc Artist.cfc BaseEntity.cfc

    Label.cfc Response.cfc ModuleConfig.cfc
  13. ModuleConfig.cfc

  14. models/services/ArtistService.cfc

  15. models/Artist.cfc

  16. models/Response.cfc

  17. THE API MODULE

  18. Created modules_app/api Created modules_app/api/models Created modules_app/api/models/models_here.txt Created modules_app/api/ModuleConfig.cfc Created modules_app/api/views

    Created modules_app/api/views/home Created modules_app/api/views/home/index.cfm Created modules_app/api/handlers Created modules_app/api/handlers/Home.cfc > coldbox create module api
  19. Created modules_app/api Created modules_app/api/models Created modules_app/api/models/models_here.txt Created modules_app/api/ModuleConfig.cfc Created modules_app/api/views

    Created modules_app/api/views/home Created modules_app/api/views/home/index.cfm Created modules_app/api/handlers Created modules_app/api/handlers/Home.cfc > coldbox create module api
  20. modules_app api config handlers BaseHandler.cfc Home.cfc ModuleConfig.cfc Router.cfc

  21. api/ModuleConfig.cfc

  22. api/ModuleConfig.cfc

  23. api/handlers/BaseHandler.cfc

  24. Home.cfc api/handlers/Home.cfc

  25. api/config/Router.cfc

  26. THE API V1 MODULE v1

  27. WHY VERSION?

  28. None
  29. None
  30. None
  31. None
  32. None
  33. The single biggest problem in communication is the illusion it

    has taken place
  34. /api /api/v1 death date

  35. HATEOAS DRIVEN API

  36. Hypermedia As The Engine Of Application State

  37. None
  38. > cd modules_app/api Created modules_app/api/modules_app/v1 Created modules_app/api/modules_app/v1/models Created modules_app/api/modules_app/v1/models/models_here.txt Created

    modules_app/api/modules_app/v1/ModuleConfig.cfc Created modules_app/api/modules_app/v1/views Created modules_app/api/modules_app/v1/views/home Created modules_app/api/modules_app/v1/views/home/index.cfm Created modules_app/api/modules_app/v1/handlers Created modules_app/api/modules_app/v1/handlers/Home.cfc > coldbox create module v1
  39. > cd modules_app/api Created modules_app/api/modules_app/v1 Created modules_app/api/modules_app/v1/models Created modules_app/api/modules_app/v1/models/models_here.txt Created

    modules_app/api/modules_app/v1/ModuleConfig.cfc Created modules_app/api/modules_app/v1/views Created modules_app/api/modules_app/v1/views/home Created modules_app/api/modules_app/v1/views/home/index.cfm Created modules_app/api/modules_app/v1/handlers Created modules_app/api/modules_app/v1/handlers/Home.cfc > coldbox create module v1
  40. modules_app v1 config handlers Albums.cfc Artists.cfc ModuleConfig.cfc Router.cfc Home.cfc Labels.cfc

    models
  41. v1/ModuleConfig.cfc

  42. v1/ModuleConfig.cfc

  43. v1/handlers/Home.cfc

  44. router.cfm

  45. v1/config/Router.cfc

  46. v1/config/Router.cfc

  47. > install route-visualizer --savedev

  48. None
  49. None
  50. None
  51. v1/handlers/Artists.cfc

  52. v1/handlers/Artists.cfc

  53. v1/handlers/Artists.cfc

  54. None
  55. WHAT IS CFFRACTAL?

  56. Views take models and return HTML

  57. CFFractal takes models and returns a serialised format of your

    choice
  58. None
  59. None
  60. None
  61. None
  62. WHY CFFRACTAL?

  63. You need to transform your business models into different types

    of data in multiple places
  64. You want to have control over what data is displayed

    depending on the endpoint
  65. You want to have control over what entity relationships are

    included depending on the endpoint
  66. > install cffractal —save

  67. None
  68. None
  69. MODEL CONSISTENCY

  70. None
  71. None
  72. // GET /albums [ { "id": 1, "name": "Be More

    Kind" } … ]
  73. // GET /albums [ { "id": 1, "name": "Be More

    Kind" } … ] // GET /category/rock [ { "id": 1, "name": "Be More Kind", "yearPublished": 2018 } … ]
  74. // GET /albums [ { "id": 1, "name": "Be More

    Kind" } … ] // GET /category/rock { "data": { "albums": [ { "id": 1, "name": "Be More Kind", "yearPublished": 2018 } … ] } }
  75. THE SOLUTION

  76. TRANSFORMERS

  77. ArtistTransformer.cfc

  78. NESTED RESOURCES

  79. ARTIST ALBUM RECORD LABEL

  80. ARTIST if( variables.consumer == foo ){ if( artist.hasAlbum() ){ result.album

    = artist.getAlbum().getMemento(); } } if( variables.consumer == foo ){ if( album.hasLabel() ){ if( structKeyExists( result, ‘album’ ){ result.album.label = album.getLabel().getMemento(); } } }
  81. THE SOLUTION

  82. “INCLUDES” CONVENTION

  83. None
  84. None
  85. None
  86. http://127.0.0.1:49653/api/v1/artists

  87. http://127.0.0.1:49653/api/v1/artists?includes=albums

  88. http://127.0.0.1:49653/api/v1/artists?includes=albums.label

  89. ArtistTransformer.cfc

  90. ArtistTransformer.cfc

  91. AlbumTransformer.cfc

  92. AlbumTransformer.cfc

  93. DON’T REPEAT YOURSELF

  94. ArtistTransformer.cfc

  95. handlers/Albums.cfc

  96. ArtistTransformer.cfc

  97. SERIALIZERS

  98. I SERIALIZED FORMATS

  99. RESULTSMAP SERIALIZER

  100. None
  101. DATA SERIALIZER

  102. None
  103. SIMPLE SERIALIZER

  104. None
  105. XML SERIALIZER

  106. None
  107. SWITCHING FORMATS

  108. None
  109. None
  110. None
  111. POST TRANSFORMATIONS

  112. Consider the API version and HATEOAS rules

  113. None
  114. None
  115. None
  116. EXTENDING TRANSFORMERS

  117. models/Artist.cfc

  118. models/BaseEntity.cfc

  119. BaseTransformer.cfc

  120. ArtistTransformer.cfc

  121. CFFRACTAL BUILDER API

  122. BUILDER METHODS item() withTransformer() withSerializer() withIncludes() collection() withExcludes() withMeta() withPagination()

    withItemCallback() convert() toJSON()
  123. None
  124. None
  125. None
  126. None
  127. None
  128. None
  129. None
  130. TESTING YOUR API

  131. None
  132. None
  133. CASE STUDIES

  134. MULTIPLE ENDPOINTS

  135. Case Study #1 v1 38 API handlers 300 lines of

    code per handler 49 transformers 100 lines of code per handler
  136. Case Study #1

  137. Case Study #1

  138. LEGACY CODE WITH ISSUES

  139. Case Study #2

  140. Case Study #2

  141. TO RECAP

  142. WHY CFFRACTAL? Transformers for output control (can be nested) “includes”

    conventions Separation of concern Encapsulation Response consistency Testable components
  143. None
  144. ADDITIONAL TOOLS

  145. None
  146. None
  147. None
  148. None
  149. None
  150. None
  151. None