Modern Functional Fluent CFML REST by Luis Majano

In this session, we will review 6 versions of the same API to take it from just working to thoroughly modern, fluent, and functional. We will review the guiding principles of software architecture, but most of the time, we will review and compare code.

Transcript

1. Modern Functional Fluent <CFML> REST APIs LED BY Luis F. Majano
2. Luis Majano About Me • CEO Ortus Solutions • Computer Engineer • Creator of all things box!
 • Documentation Weirdo!
 • www.luismajano.com
 @lmajano @ortussolutions
3. Modernize or Die™
 Podcasts www.youtube.com/c/OrtusSolutions/
4. •Age of APIs •Guiding Principles •Look at the past to see the future •API Evolution Agenda
5. - Harold Abelson Programs must be written for people to read, and only incidentally for machines to execute. Inspiration
6. • Every company is a software company • Deal with two concerns most of the time: APIs Front-Ends (maybe) • We must be: Agile Connected Sustainable Age of APIs
7. Guiding Principles • Cohesion • Readability • Reusability • Encapsulation • Abstractions • Testability • Sanity C.R.R.E.A.T.S
8. You can never escape it….
9. Crux of Our Session
10. Ortus Philosophy on Code Make it work! Then Make it pretty!
11. • Hit .cfm pages and return JSON • Hit .cfc’s with remote access and returnFormat=json API - version 0 /users/getdata.cfm?page=4&exclude=data /cfcs/UserService.cfc?method=login&email=#email#&password=#password# /cfcs/DataService.cfc?method=list&max=40
12. √ Pros X Cons • Easy to write • Manual Processes • Status codes manually • Headers manually • CORS manually • Inline queries? • No MVC • Maybe some CFCs • Automated tests? • Ugly URIs • No self documentation • Expose our fi le structures • Breaks all the rules of encapsulation • How do we secure it? • What if we rename fi les? • How do I version it? API - version 0
13. • Using native CFML REST • We can leverage HTTP methods • We can leverage URL resources and path params • CFC and annotation-driven GET /rest/myapp/users/page/4/exclude/data POST /rest/myapp/users/login?email=#email#&password=#password# GET /rest/myapp/studentService/Thomas-235 API - version 0.5
14. • CFC Driven • Can leverage status codes • Can leverage verbs • Can leverage URIs • Maybe testable • Instant grati fi cation • Manual Processes • CORS manually • Security manually • Every URL starts with /rest/{appname} • BIF method for custom status codes,
 
 headers, content • Impossible to test or mock (bound to the engine) • restSetResponse() • Register base URLs via admin, admin API or methods • Security is a pain since CFC methods are called • No documentation • Maybe testable • Relies on pure inheritance for reuse • Careful on not setting this.restSettings.location, EVERY CFC is scanned. API - version 0.5 √ Pros X Cons
15. • I’ve written APIs like that • I still have APIs like that • I admit it • I’m scared when I go back to maintain them • I have cried in a dark corner • I see no issues with it • How can we do things differently? • Modern • Functional • Fluent • Testable What do we do? We have all done it!
16. Why …. • More human code • Less boilerplate • Focus on what it should do and not how to do it (BDD) • Focus on testing • Easier to produce • Easier to maintain • Let the tools do the work ...and dare I say it, FUN!!!
17. • Use ColdBox HMVC • Version the API -> 6 versions • Database Versioning -> cfmigrations • BDD Tests • Iterate to make it more human • Reuse the ecosystem • Validation • Cors • Docs Testing… Build a Rants API github.com/lmajano/modern-functional- fl uent-cfml-rest
18. • ColdBox Modular REST:
 
 > coldbox create app skeleton=rest-hmvc
 • Versioned • Handlers are RestHandlers • Global customizable/mockable Response object: 
 data, errors, status, messages, pagination • Convention-based routing for pretty URLs • Using service objects with queryExecute() to return query data • BDD Tests
 API - version 1
19. API - version 1
20. • Refactor to use a Router instead of convention routing • Refactor to use array of structs instead of queries • Refactor to use structs for GET operations • Refactor to eliminate temporary variable assignments ( fl uent and readable) • CBValidation instead of manual validation • Create an exists() function instead of getting records • Use get() functions for consistency • More BDD Tests! API - version 2
21. • Predictable routing with ColdBox API Resourceful Routes • Uniformity on routing • Less Boilerplate • Introduce a BaseService object for encapsulation/abstraction • exists(), existsOrFail() • getOrFail(), get() • delete() • Use validateOrFail() for less boilerplate from cbValidation • Human and fl uent levels are increasing+++++ API - version 3
22. • Using OOP => Create Entities to model behavior • Better visualization of what a Rant is or User is • Encapsulated validation constraints in entities • Encapsulated marshaling of data to a function : getMemento() • Services uses a populator to in fl ate queries to objects • Return the full entity memento on create and updates instead of just the id API - version 4
23. • Populate Entities with populateModel() and remove boilerplate • Use a preHandler for paraming incoming variables • Use Mementifer to stop building data manually • Add a global new() for all services via BaseService.cfc • Make your Objects fl uent and functional by adding a BaseEntity.cfc • getOrFail() • validateOrFail() • populate() • save() • delete() • Basic memento settings • More complex validation
 API - version 5
24. • Make a catch all resource for invalid routing • Add mementi fi er runtime includes, excludes for fl exibility • Custom Includes • Relationships • More fl uency • Event Caching • Add Swagger/OpenAPI Docs • More Tooling • Install cbswaggerUI • RestFox API - version 6
25. Luis Majano CEO and Software Architect Ortus Solutions, Corp Thank You! @lmajano @ortussolutions P/F: E-mail: 1-888-557-8057 lmajano@ortussolutions.com www.ortussolutions.com