Itb 2021 - Bulding Quick APIs by Gavin Pickin

Building Quick APIs
by Gavin Pickin
https://github.com/gpickin/itb2021-building-quick-apis

Gavin Pickin
Who am I?
• Software Consultant for Ortus Solutions
• Work with ColdBox, CommandBox, ContentBox
APIs and VueJS every day!
• Working with Coldfusion for 22 years
• Working with Javascript just as long
• Love learning and sharing the lessons learned
• From New Zealand, live in Bakersﬁeld, Ca
• Loving wife, lots of kids, and countless critters
@gpickin

What is this talk?
We will setup a secure API using ﬂuent query language - and
you’ll see how quick Quick development can be!
We will use
● ColdBox
● ColdBox’s built in REST BaseHandler
● Route Visualizer
● CBSecurity
● Quick ORM

What is this talk not?
● We will not be adding an API to a Legacy Site
● We will not be adding an API to a non ColdBox site
● It is not my CF Meetup Talk “Building APIs with
ColdFusion Part 1”
https://www.youtube.com/watch?v=UdgRt8HIKD0
BUT YOU COULD DO ALL OF THESE THINGS
WITH THE KNOWLEDGE FROM THIS TALK

Why should I give this talk?
• I build a lot of APIs for Customers
• I have seen many different ways to build an API
• I’m going to share some of the lessons I have learned.
• I try to present in step by step follow along later
format that I think you’ll love
• Hopefully you’ll learn something
• Hopefully it will be useful.

What is an API?
API is an application programming interface
More commonly when someone says API today they think of
an JSON API, usually we hope for a REST API but not always.
APIs can be xml, soap, but it’s very common to talk about
JSON apis, and that’s what we’re talking about today.
Although most of it is relatable.

REST JSON API vs JSON API
What is REST
REST is acronym for REpresentational State Transfer. It is
architectural style for distributed hypermedia systems and
was ﬁrst presented by Roy Fielding in 2000 in his famous
dissertation.
All REST are APIs but not all APIs are REST.

Guiding Principles of REST
● Client–server
● Stateless
● Cacheable
● Uniform interface
● Layered system
The key abstraction of information in REST is a resource. Any information
that can be named can be a resource: a document or image, a temporal
service, a collection of other resources, a non-virtual object (e.g. a person),
and so on. REST uses a resource identiﬁer to identify the particular resource
involved in an interaction between components.

What App are we working on?
SOAPBOX API - An API for a twitter clone we built for our ColdBox Zero to Hero Training.

Let’s do this!!!
Start up CommandBox!!!

Create a ColdBox App
box coldbox create app soapbox-api
This installs:
● ColdBox
● TestBox
● CommandBox-dotEnv
● CommandBox-cfconfig
● CommandBox-cfformat

Let’s update our .env
● Change the connection string to match our DB - soapboxapi
● Change the DB_DATABASE to match our DB - soapboxapi
● Change ports, user name and password to match

Let’s start our server
That port matches the testbox runner in the box.json
http://127.0.0.1:53163/ - our site
http://127.0.0.1:53163/tests/runner.cfm - our tests
box start port=53163

Let’s plan our API
What is an Example URL - /api/v01/users
We’re going to make API a module with a V01 module inside of it.
● Add modules_app folder for this apps custom modules
● Add modules_app/api folder with ModuleConfig.cfc
● Add modules_app/api/modules/api-v01 folder with ModuleConfig.cfc
API - V01

Let’s build out our API V01 Module
● Add modules_app/api/modules/api-v01/config Folder with Router.cfc
● Setup the base route of “/” to go to main.index
● Add api-v01/handlers/main.cfc which extends coldbox.system.RestHandler
● Add index event in the main handler
● Index event should sets data in the response object to welcome the user to
the api.
http://127.0.0.1:53163/api/v01
API - V01

Let’s plan our API
USER resource
GET /api/v02/users - get a list of users
POST /api/v02/users - create a new user
GET /api/v02/users/:userID - get a single user
POST /api/v02/users/:userID - update a single user
DELETE /api/v02/users/:userID - delete a single user
API - V02

Add User Resource to Router.cfc
resources(
resource = "users",
handler = "users",
parameterName = "userID",
only = [ "index", "show", "create", "update", "delete" ]
);
API - V02

Let’s view our Routes
box install route-visualizer
API - V02

Build our Users Handler
function index( event, rc, prc ){
event.getResponse().setData( "List Users" );
}
function create( event, rc, prc ){
event.getResponse().setData( "Create User" );
}
API - V02
http://127.0.0.1:53163/api/v02/users

Secure our CUD Actions
Let’s use CBSecurity to lock down our non READ functionality
● CREATE
● UPDATE
● DELETE
API - V03

Install CBSecurity
Add the Config to your config/ColdBox.cfc
Add a JWT Secret incase .env has a blank one
Add “api-v03:main.index” for “invalidAuthenticationEvent”
Add “api-v03:main.index” for “invalidAuthorizationEvent”
API - V03
box install cbsecurity

Add Secured Metadata
function create( event, rc, prc ) secured{
event.getResponse().setData( "Create Users" );
}
API - V03

Check our Security
http://127.0.0.1:53163/api/v03/users?_method=post
You will get redirected to main.index
API - V03

Updating Redirects for API Authentication
and Authorization Issues
You should really setup your main ColdBox app for an HTML page and
your API module for an API page
Add settings to the API-v04 Module Config
Add “api-v04:main.index” for “invalidAuthenticationEvent”
Add “api-v04:main.index” for “invalidAuthorizationEvent”
API - V04

Updating Redirects for API Authentication
and Authorization Issues
http://127.0.0.1:53163/api/v04/users/?_method=post
Now we are redirected to an API Handler
You can add new methods for onInvalidAuth and or
onInvalidAuthorization to be more specific in your responses
API - V04

Install and Conﬁgure Quick
add a datasource definition in Application.cfc
API - V05
this.datasource = "soapboxapi";
box install quick

Create our Quick User Entity
component extends="quick.models.BaseEntity" accessors="true" {
property name="id" type="string";
property name="username" type="string";
property name="email" type="string";
property name="password" type="string";
}
API - V05

Quick is Smart
● Quick guesses the table is named Users because the entity is User
● Quick guesses the Primary Key is ID
● Quick uses the Datasource defined in the Application.cfc
● Quick can make a Virtual Service for us from a WireBox Injection
property name="userService" inject="quickService:User@api-v05";
Quick does a lot for us
API - V05

Show a User
function show( event, rc, prc ){
event.paramValue( "userID", 0 );
event.getResponse().setData(
userService
.findOrFail( rc.userID )
.getMemento()
);
}
API - V05

Show a User
http://127.0.0.1:53163/api/v05/users/2
API - V05

What if we can’t ﬁnd that User?
http://127.0.0.1:53163/api/v05/users/x
404 response
API - V05

Return a list of Users
userService
.asMemento()
.get()
);
}
API - V06

What is asMemento()
asMemento() is a special function that tells quick you want to map over
all of the objects in the array, and call getMemento() on all of the items
.get().getMemento() doesn’t work because .get() returns an array
As memento is essentially the following done for you.
...get().map( (item) => { return item.getMemento() } );
API - V06

Reinit and check the API
http://127.0.0.1:53163/api/v06/users/
API - V06

Conﬁguring Mementiﬁer
● We don’t want to return all of the fields
● For example Password, even if it is encrypted
https://github.com/coldbox-modules/mementifier
API - V07

Mementiﬁer Inline Excludes
API - V07
userService
.asMemento(
excludes=[ "password" ]
)
.get()
http://127.0.0.1:53163/api/v07/users

Mementiﬁer - Inline Includes
API - V08
userService
.asMemento(
includes=[ "id", "username", "email" ],
ignoreDefaults = true
)
.get()
http://127.0.0.1:53163/api/v08/users

Mementiﬁer - Entity Conﬁg
API - V09
//models/User.cfc
this.memento = {
defaultIncludes=[ "username", "email" ],
neverInclude=["password"]
}
http://127.0.0.1:53163/api/v09/users/2

Mementiﬁer - Inline Includes
API - V10
userService
.asMemento(
includes=[ “ID” ]
)
.get()
);
}
http://127.0.0.1:53163/api/v10/users/

Using Where to Filter Users
API - V11
event.paramValue( "username_filter", "" );
userService
.where( "username", "like", '%#rc.username_filter#%')
.asMemento(
includes="ID"
)
.get()
);
http://127.0.0.1:53163/api/v11/users?username_filter=gp

Using Scope to Filter Users
API - V12
//handler - use this
userService.whereUsernameLike(rc.username_filter)
// not this
userService.where( "username", "like", '%#rc.username_filter#%')
// models/User.cfc
function scopeWhereUsernameLike( qb, filter ){
qb.where( "Username", "like", '%#filter#%' )
}

Using Dynamic Where to Match Users
API - V13
userService
.whereUsernameLike(rc.username_filter)
.whereUsername(rc.username)
.asMemento(
includes="ID"
)
.get()

Using When for Empty Variables
API - V14
userService
.when( len( rc.username ), function( q ) {
q.whereUsername(rc.username)
}
.asMemento(
includes="ID"
)
.get()

API - V14
userService
}
.asMemento(
includes="ID"
)
.get()
http://127.0.0.1:53163/api/v14/users?username=gp

API - V14
userService
}
.asMemento(
includes="ID"
)
.get()
http://127.0.0.1:53163/api/v14/users?username=gpickin

Using ‘Or’ for Similar Filters
API - V15
userService
}
.asMemento(
includes="ID"
)
.get()
http://127.0.0.1:53163/api/v14/users?username=gpickin&username_filter=luis

Using ‘Or’ for Similar Filters
API - V15
userService
.orWhere( function(q){
q.when( len( rc.username ), function( q2 ) {
q2.orwhereUsername(rc.username)
})
})
http://127.0.0.1:53163/api/v14/users?username=gpickin&username_filter=lui

Setup Rant Resource
API - V16
resources(
resource = "rants",
handler = "rants",
parameterName = "rantID",
only = [ "index", "show", "create", "update", "delete" ]
);

Setup Rant Handler
API - V16
/**
* Manage Rants API Handler
*
*/
component extends="coldbox.system.RestHandler "{
/**
* Display a list of Rants
*/
event.getResponse().setData( "Show Rants");
}
/**
* Create a Rant
*/

Test Rant Resource
API - V16
http://127.0.0.1:53163/api/v16/rants? http://127.0.0.1:53163/api/v16/rants/6

Create Rant Entity
API - V17
component extends="quick.models.BaseEntity" accessors="true" {
property name="id" type="string";
property name="body" type="string";
property name="createdDate" type="date";
property name="modifiedDate" type="date";
property name="userID" type="string";
}

Inject Rant Service and Return Rants
API - V17
property name="rantService" inject="quickService:Rant@api-v17";
rantService
.asMemento()
.get()
);
}
http://127.0.0.1:53163/api/v17/rants

Paginate the Rants Returned
API - V18
http://127.0.0.1:53163/api/v17/rants
● We don’t want to return every record, it will only
grow longer and longer over time, and
performance will suffer
● ColdBox RESTBaseHandler already has Pagination
information
● Let’s use Quick’s Paginate function

API - V18
http://127.0.0.1:53163/api/v18/rants
rantService
.asMemento()
.paginate(1,10)
);

API - V18
http://127.0.0.1:53163/api/v18/rants
rantService
.asMemento()
.paginate(1,10)
);
Why do we have 2 sets of Pagination Data???

Use SetDataWithPagination
API - V19
http://127.0.0.1:53163/api/v19/rants
event
.getResponse()
.setDataWithPagination(
rantService
.asMemento()
.paginate(1,10)
);

Return Rants User Information
// Add User Relationship to Rant.cfc
function user(){
return hasOne( "User@api-v20", "id", "userID" );
}
API - V20
// Update Rants.cfc handler
event.getResponse().setDataWithPagination(
rantService
.asMemento( includes="user" )
.paginate(1,10)
);

API - V20
http://127.0.0.1:53163/api/v20/rants

API - V20
● Nested Fields
● What if we just want 1 field?
● How is Mementifier getting the
data??
http://127.0.0.1:53163/api/v20/rants

Return Rants with SubSelect User Information
API - V21
event.getResponse().setDataWithPagination(
rantService
.addSubselect( "username", "user.username")
.asMemento()
.paginate(1,10)
);
http://127.0.0.1:53163/api/v21/rants

Return a Count of Rants for Users
API - V22
// Add Rants Relationship to models/User.cfc
function rants(){
return hasMany( "Rant@api-v22", "userID", "id" );
}
// Update users.cfc handler
userService
.withCount( "rants" )
.asMemento(
includes=["ID","rantsCount"]
)
.get()
http://127.0.0.1:53163/api/v22/users

Return Recent Rants for Users
API - V23
//Router.cfc
get( "/users/:userID/rants"
, "userRants.index" );
// Handlers/userRants.cfc
event.paramValue( "userID", "" );
event.paramValue( "page", 1 );
event.paramValue( "per_page", 10 );
event.getResponse().setDataWithPagination
(
rantService
.where( "userID", rc.userID )
.orderBy( "createdDate", "desc" )
.asMemento()
.paginate( rc.page, rc.per_page )
);
}
http://127.0.0.1:53163/api/v23/users/2/rants

Create a new Rant
API - V24
http://127.0.0.1:53163/api/v24/rants?_method=post&userID=2&body=Adding%20a%20Rant
event.paramValue( "userID", "" );
event.paramValue( "body", "" );
userService
.findOrFail( rc.userID )
.rants()
.create( { body: rc.body } );
event.getResponse().setData( "Rant Created" );
}

View the new Rant
API - V24
http://127.0.0.1:53163/api/v24/users/2/rants

What if we add an Empty Rant
API - V24
http://127.0.0.1:53163/api/v24/rants?_method=post&userID=2&body=
Not User
Friendly

Validate a new Rant
API - V25
box Install cbvalidation

Validate a new Rant - Handler Constraints
API - V25
var validationResult = validate(
target = rc,
constraints = { body : { required : true } }
)
if ( !validationResult.hasErrors() ) {
// Normal API Response
} else {
event.getResponse()
.setError( true )
.addMessage( validationResult.getAllErrors() )
.setStatusCode( 400 )
.setStatusText( "Validation error" );
}

Validate a new Rant - Entity Constraints
API - V26
//Rant.cfc
this.constraints = {
body : { required : true },
userID: { required : true, type : "numeric" }
};
// Handler/rants.cfc
var rant = getInstance( "Rant@api-v26" )
.fill({ body: rc.body, userID: rc.userID });
validateOrFail( rant );
var user = userService.findOrFail( rc.userID );
rant.save();
event.getResponse().setData( "Rant Created" );

API - V26
Body is missing or empty

API - V26
http://127.0.0.1:53163/api/v26/rants?_method=post&userID=xxx&body=MyRant
UserID is not numeric

API - V26
http://127.0.0.1:53163/api/v26/rants?_method=post&userID=0&body=MyRant
UserID is numeric but not in User table

Edit a Rant
API - V27
event.paramValue( "rantID", 0 );
event.paramValue( "body", "" );
var rant = rantService.findOrFail( rc.rantID )
.fill({ body: rc.body });
validateOrFail( rant );
rant.save();
event.getResponse().setData( "Rant Updated" );

Edit a Rant - Success
API - V27
http://127.0.0.1:53163/api/v27/rants/178/?_method=put&body=Yes%20thats%20is%20right

Edit a Rant - Missing Body
API - V27
http://127.0.0.1:53163/api/v27/rants/178/?_method=put&body=

Delete a Rant
API - V28
function delete( event, rc, prc ){
event.paramValue( "rantID", 0 );
var rant = rantService.findOrFail( rc.rantID ).delete();
event.getResponse().setData( "Delete a Rant" );
}

Delete a Rant that doesn’t Exist
API - V28
http://127.0.0.1:53163/api/v28/rants/70000/?_method=delete

Delete a Rant that does Exist
API - V28

Secure the Add / Edit Rant
function create( event, rc, prc ) secured{ … }
function update( event, rc, prc ) secured{ … }
API - V29
NOT LOGGED IN
http://127.0.0.1:53163/api/v29/rants/178/?_method=put&body=hiya

Secure the Delete Rant with a Special Permission
API - V29
function delete( event, rc, prc ) secured="RANT__DELETE"{ … }
NOT LOGGED IN

Create a Generate JWT Endpoint
//Router.cfc
post( "/login", "session.create" );
delete( "/logout", "session.delete" );
//handlers/session.cfc
token = jwtAuth().fromuser( userService.findOrFail( 2 ) );
event.getResponse()
.addMessage( "Token Created" )
.setData( token );
}
function delete( event, rc, prc ){
jwtAuth().logout();
event.getResponse().setData( "Delete Session - Log Out" );
}
API - V30

Decorate User.cfc Entity for JWT
API - V30
/**
* A struct of custom claims to add to the JWT token
*/
struct function getJWTCustomClaims(){
return {};
}
/**
* This function returns an array of all the scopes that should be attached to the JWT
* token that will be used for authorization.
*/
array function getJWTScopes(){
return [];
}

Hit Generate JWT Endpoint
API - V30
http://127.0.0.1:53163/api/v30/login?_method=post

Use JWT to Add a Rant
API - V30

But Wait, there’s more (I wish)
I really wanted to show you more, but we don’t have all day.
Join me at the CF Online Meetup where I do this again, maybe
slower/better
Join me for the October Ortus Webinar as we build on top of this.
We might make a CFCasts series out of this if you like this style of
content

You can use images and add them opacity at 90%. This will blend the image
with the gradient background. This is a good option for subtitles also.
Testing APIs with TestBox
with Javier Quintero
Up Next

E-mail: gavin@ortussolutions.com
Twitter: @gpickin
Gavin Pickin
Senior Software Consultant
Ortus Solutions, Corp
https://github.com/gpickin/itb2021-building-quick-apis

Itb 2021 - Bulding Quick APIs by Gavin Pickin

Recommended

Recommended

More Related Content

What's hot

What's hot (8)

Similar to Itb 2021 - Bulding Quick APIs by Gavin Pickin

Similar to Itb 2021 - Bulding Quick APIs by Gavin Pickin (20)

More from Gavin Pickin

More from Gavin Pickin (12)

Recently uploaded

Recently uploaded (20)

Itb 2021 - Bulding Quick APIs by Gavin Pickin