Workshop

Building a REST API for the Modern Developer

This workshop will walk us through creating a ColdBox REST API using the Ortus tools. We will use CommandBox to configure and host the API site using environment variables and cfconfig, the ColdBox RESTFul handler to return a standard payload, JWT authentication using cbSecurity to secure our calls, cbValidation to validate our incoming data, Swagger annotations to document our APIs, BDD Integration tests to test our API calls, and qb for creating our database tables and accessing our data. In addition, we will use PostMan to assist with development as well as ngrok to serve our APIs, allowing us to connect to each other.

 

Who is the audience for the workshop?

The audience for this workshop is a CFML Developer who wants to build a CFML REST API backend and secure it JWT authentication. Familiarity with CommandBox and ColdBox would be helpful but is not required.

 

Why should I take the workshop?

You will learn how to build a modern REST API using a combination of scaffolding templates, modules (cbSecurity, cbValidation, cbSwagger, cbSwagger-UI, and qb ), routing, and best practices.

This workshop will show you how you can authenticate that API and use JWT to secure the calls as well as create documentation for the APIs. In addition, you will also be able to write tests to check that your API is performing as expected.

 

App User Stories

Use questions that will test the students on their understanding of the workshop they just attended and reinforce Ortus products.

• CommandBox
  • Create your environment file with variables
  • Configure your .cfconfig file
  • Install required modules
  • Review the box.json file to see how it works with the site
  • Configure migrations in box.json
  • Create the site using the REST-HMVC Template
• API
  • Login
    • Generate JWT
  • Logout
    • Clear JWT
  • CRUD
    • List
    • Show
    • Create
    • Update
    • Delete
  • Secure calls
  • Validate input
  • Document functions
  • Test calls

 

What will the workshop cover

1. Using CommandBox to set up your site
2. Creating a ColdBox REST API
3. Creating Database Tables via Migrations
4. Setting up our Database Models and Services
5. Use API Resourceful Routes
6. Implementing JWT authentication
7. Using Postman to preview API Responses
8. API Documentation
9. API Testing
10. Swagger UI Tooling

If we have time, we will also talk about nice to-haves like

• Debugging with cbDebugger
• Show an example of CI/CD

 

Prerequisites

Programming Knowledge: Basic knowledge of API concepts, ColdFusion. Familiarity with CommandBox and ColdBox is great.

Hardware and software: A laptop with CommandBox installed. You will need a Code Editor (VS Code or your choice of IDE), a MySQL client to connect to your database, PostMan, and ngrok (if you want to let others connect to your API).

We will be using MySQL 8, so it is recommended you have MySQL 8 installed locally or Docker to run MySql 8 Container with our Docker Compose file. You will see significant performance benefits running the database locally vs. running a remote DB, which we will provide as a backup.

Required

• CommandBox - https://www.ortussolutions.com/products/commandbox
• Postman - https://www.postman.com/
• IDE for editing CFML and VueJS (javascript)
• MySQL 8 ( installed locally, with docker-compose.yml or will provide remote server )
• MySQL DB Client
• ngrok - https://ngrok.com

Preferred

• IDE
  • VS Code - https://code.visualstudio.com/download
• MySQL Clients
  • Sequel Pro for Mac - https://sequelpro.com/
  • HeidiSQL for Windows - https://www.heidisql.com/

Recommended VS Code Extensions

• CFML by KamasamaK

 

You will leave the workshop with:

You will have all the building blocks you need and walk away with a working REST API that you can secure.

You will leave with an understanding of:

1. Basics of using CommandBox to host your site
2. Best Practices for Creating ColdBox REST APIs
3. How to secure your API using JWT authentication
4. How to use qb migrations to build your database tables
5. Adding validation to your APIs
6. How to use PostMan to test your APIs
7. How to test your APIs
8. Documenting your APIs