Building an API with cffractal and ColdBox

Transcript

1. @coldfumonkeh Matt Gifford Building an API with CFFRACTAL and COLDBOX
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
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?
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
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
51. v1/handlers/Artists.cfc
52. v1/handlers/Artists.cfc
53. v1/handlers/Artists.cfc
55. WHAT IS CFFRACTAL?
56. Views take models and return HTML
57. CFFractal takes models and returns a serialised format of your choice
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
69. MODEL CONSISTENCY
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
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
101. DATA SERIALIZER
103. SIMPLE SERIALIZER
105. XML SERIALIZER
107. SWITCHING FORMATS
111. POST TRANSFORMATIONS
112. Consider the API version and HATEOAS rules
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()
130. TESTING YOUR API
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
144. ADDITIONAL TOOLS