RESTFul tools for lazy experts

ColdBoxRESTful Roadshow

Relax: ReSTful Tools For Lazy Experts

March 16, 2016

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


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


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


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.


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?


Jon ClausenWe call in the big guns :)


Jon Clausen


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.”


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



● Responsive● Descriptive● Exportable● Extendable● Navigable

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


Take the best features of other API documentation design and testing tools and integrate them into a single workflow

And many, many more...


Let’s Play!


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.



GETPOSTPUT

PATCHDELETE

HEADOPTIONS



➔ 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”


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


RESTful Web Services Cookbook: Solutions

for Improving Scalability and SimplicitySubbu Allamaraju



https://www.google.com/search?tbo=p&tbm=bks&q=inauthor:%22Subbu+Allamaraju%22&source=gbs_metadata_r&cad=7

https://www.google.com/search?tbo=p&tbm=bks&q=inauthor:%22Subbu+Allamaraju%22&source=gbs_metadata_r&cad=7

Technology

RESTFul tools for lazy experts