restful tools for lazy experts
TRANSCRIPT
Who am I - GavinI am Software Consultant for Ortus
I run the CFML Repo
Blog on gpickin.com
On twitter @gpickin
Doing ColdFusion since 1999
Relax: RESTful Tools for Lazy Experts - March 16, 2016
What is ColdBox RelaxA set of ReSTful tools to simplify your development.
Use it to:
Describe ReSTful Web Services
Document ReSTful Web Services
Test ReSTful Web Services
Relax: RESTful Tools for Lazy Experts - March 16, 2016
What else can Relax do?Generate ColdBox Routes from described Web Services
Export Documentation in many formats - HTML, PDF, and more
Keep history of Relax Tests so you can rebuild your requests
Integrate with LogBox, use RelaxLogs to monitor DB Entries
Describe your Web Service with a programmitc DSL
Relax: RESTful Tools for Lazy Experts - March 16, 2016
Why use Relax over DocBoxDocBox gives you quality documentation for developers
Relax gives you API consumer based documentation with organization and drill down capabilities
Interact with your API and gain other benefits like Route Generation and test history
One location for all of your tooling
Relax: RESTful Tools for Lazy Experts - March 16, 2016
Why not use other API ToolsUsing a Native tool gives you direct access to the code for power and convenience
Easily update JSON samples and tests instantly when code is updated, without having to re-upload into other tools
Relax can be easily run locally on your dev machine, with CommandBox, you can be setup in minutes and working with your API.
Relax: RESTful Tools for Lazy Experts - March 16, 2016
But wait, there’s moreWith all of the focus on Mobile and Javascript front ends and CFML API backends, we need to keep improving our tools
We can make Relax better, learning from other tools and languages
So how do we do that?
Relax: RESTful Tools for Lazy Experts - March 16, 2016
API Documentation:Umm… why do would I need a tool for it?
“I agree that documentation is a great thing, but I’ve got too much work on my plate to do much of it. This would just add another *thing*”
“My team practices Agile methods, which de-emphasize documentation over maintaining flexibility and producing usable software. We can just comment our code, when needed.”
“My API is for internal consumption only. Only myself and other developers on my team will use it.”
Relax: RESTful Tools for Lazy Experts - March 16, 2016
API Documentation:A business case for developers● Helps to define coding conventions● Allows API evolution to maintain consistency and
standards● Decreases time for consumers to iterate features which
consume the API● Provides flexibility in early development phases by
allowing members, owners, and stakeholders to visualize the product and discuss future needs
Relax: RESTful Tools for Lazy Experts - March 16, 2016
RELAX:The Next Generation
● Open and transferrable documentation using OpenAPI (fka Swagger)
● Maintain backward compatibility for RelaxDSL (for a time)● Minimize the need for duplication of effort● Streamline the drill-down process to the response level● Make documentation authoring and revisions pain-free
Relax: RESTful Tools for Lazy Experts - March 16, 2016
RELAX:The Next Generation● Drill down quickly
to paths, methods, schemas and samples
● References and internal document links
● Extend OpenAPI schema to near-infinite levels
RELAX:The Next Generation● Fully recursive to allow for
automation and uniform consumption of documentation resources
RELAX:The Next Generation
Take the best features of other API documentation design and testing tools and integrate them into a single workflow
And many, many more...
Addendum:API Architecture - Lessons Learned
● Maintain consistency in responses to minimize conditionals in consumption
● Implement your paging and throttling strategies *NOW*!● Standardize error handling● Less is *more* (Massive data dumps kill your API)● Marshall deeply nested arrays into hashmap
representations, whenever possible. Recursion kills.
Relax: RESTful Tools for Lazy Experts - March 16, 2016
Addendum:API Architecture - Lessons Learned
GETPOSTPUT
PATCHDELETE
HEADOPTIONS
Relax: RESTful Tools for Lazy Experts - March 16, 2016
Addendum:API Architecture - Lessons Learned
➔ 200 - “You wanted it... Here you go, buddy:”
➔ 201 - “I’ve created something new for you!”➔ 202 - “Your request is accepted, here’s a
URL so you can check the status:”➔ 203 - “Here’s a record, but we haven’t
confirmed persistence”➔ 204 - “I deleted what you told me. Now it’s
nothing, so... Here’s nothing!:”➔ 205 - “A record has been updated while you
were slacking off. Re-request the data and refresh your view.”
➔ 206 - “There are, like, a gazillion rows, man. Here’s 25 of them so I don’t break”
Relax: RESTful Tools for Lazy Experts - March 16, 2016
Addendum:Read on, and keep coding like someone left the firewall open...
The REST API Design HandbookGeorge Reese
eBook - 2012
Note: $5!
REST in Practice:
Hypermedia and Systems ArchitectureIan Robinson, Jim Webber, and Savas
Parastatidis
"O'Reilly Media, Inc.", 2010
RESTful Web APIsLeonard Richardson and Mike Amundsen
"O'Reilly Media, Inc.", 2007
RESTful Web Services Cookbook: Solutions
for Improving Scalability and SimplicitySubbu Allamaraju
"O'Reilly Media, Inc.", 2010
Relax: RESTful Tools for Lazy Experts - March 16, 2016