Modern Functional Fluent REST APIs LED BY Luis F. Majano

Luis Majano About Me • CEO Ortus Solutions • Computer Engineer • Creator of all things box!
 • Documentation Weirdo!
 • www.luismajano.com
 @lmajano @ortussolutions

Modernize or Die™
 Podcasts www.youtube.com/c/OrtusSolutions/

•Age of APIs •Guiding Principles •Look at the past to see the future •API Evolution Agenda

- Harold Abelson Programs must be written for people to read, and only incidentally for machines to execute. Inspiration

• 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

Guiding Principles • Cohesion • Readability • Reusability • Encapsulation • Abstractions • Testability • Sanity C.R.R.E.A.T.S

You can never escape it….

Crux of Our Session

Ortus Philosophy on Code Make it work! Then Make it pretty!

• 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

√ 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

• 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

• 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

• 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!

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!!!

• 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

• 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

API - version 1

• 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

• 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

• 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

• 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

• 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

Luis Majano CEO and Software Architect Ortus Solutions, Corp Thank You! @lmajano @ortussolutions P/F: E-mail: 1-888-557-8057 [email protected] www.ortussolutions.com