REST (Representational State Transfer) is an architectural style for web APIs, not a ColdFusion-specific feature. ColdFusion has built-in support for building REST services since ColdFusion 10, but before touching that syntax, this lesson covers what REST actually means: HTTP methods, resource-based URLs, and JSON responses, the concepts the next lesson's CFML implementation is built on top of.
Learning Objectives
After completing this lesson, you'll be able to:
- Explain what REST actually is, and why it's an architectural style, not a specific technology.
- Use the standard HTTP methods for what they conventionally mean.
- Design resource-based URLs instead of action-based ones.
- Recognize where ColdFusion's own REST support and the separate API Manager tool each fit in.
The Basic REST Request/Response Flow
Client Sends HTTP Request
Server Identifies the Resource (URL) and Action (Method)
Server Processes It
Client Gets a JSON Response
The HTTP Methods REST Actually Uses
| Method | Conventional Meaning |
|---|---|
| GET | Retrieve a resource, should never change data |
| POST | Create a new resource |
| PUT | Replace/update an existing resource |
| DELETE | Remove a resource |
| HEAD | Like GET, but returns only headers, no body |
| OPTIONS | Reports which methods a resource actually supports |
ColdFusion's own REST implementation supports all six of these methods natively.
A Real Example: Resource-Based URL Design
REST URLs are built around resources (nouns), with the HTTP method carrying the action, not the URL itself. This is exactly the shape a real, working CRUD API for a users resource takes:
| What It Does | Method + URL |
|---|---|
| List every user | GET /rest/api/users |
| Get one specific user | GET /rest/api/users/profile/{id} |
| Create a new user | POST /rest/api/users/create |
| Update an existing user | PUT /rest/api/users/update/{id} |
| Delete a user | DELETE /rest/api/users/delete/{id} |
Notice the resource (users) stays constant across every row, only the HTTP method and the specific id in the URL change. An action-based alternative, like /getUser?id=5 or /deleteUser?id=5 for every operation, is exactly what REST's resource-based convention avoids.
A First Look at ColdFusion's Own REST Support
The next lesson covers this in full depth, this is just enough to see the shape of it. A CFC becomes a REST resource with rest="true", and a function becomes callable over HTTP with access="remote" and an httpmethod.
<cfcomponent rest="true" restpath="restService">
<cffunction name="sayHello" access="remote" returntype="String" httpmethod="GET">
<cfreturn "Hello World">
</cffunction>
</cfcomponent>This would be reachable at a URL shaped like http://server/rest/[ApplicationName]/restService. ColdFusion also handles JSON/XML serialization implicitly based on the client's Accept header, no manual encoding needed for a basic case.
A Real Distinction: ColdFusion API Manager Is a Separate Tool
ColdFusion API Manager is not how you build a REST API in CFML, it's a standalone gateway product that sits in front of APIs (CFML-based or otherwise) that already exist. Its job is monitoring, rate-limiting/throttling, securing (API keys, OAuth2, basic auth), and analytics, not writing the endpoint logic itself.
Common Beginner Mistakes
Treating REST as a specific ColdFusion feature rather than a general architectural style
REST is a pattern that applies across languages and platforms. ColdFusion's rest="true"/httpmethod syntax is just one implementation of it, not REST itself.
Using GET for an operation that changes data
GET is conventionally expected to be safe, calling it shouldn't modify anything. An operation that deletes or updates data belongs on DELETE or PUT/POST instead.
Building action-based URLs like /getUser or /deleteUser
REST convention keeps the URL centered on the resource (/users/{id}) and lets the HTTP method carry the action, rather than encoding the action into the URL itself.
Assuming API Manager is required just to expose a REST API at all
It's an optional gateway layer for production API governance (rate limits, analytics, security policies), not a requirement for building or calling a REST endpoint in the first place.
Best Practices
- Design URLs around resources (nouns), and let the HTTP method carry the action.
- Match the HTTP method to what it conventionally means, GET for reads, POST for creation, PUT for full updates, DELETE for removal.
- Return a proper JSON response with a sensible structure, not an ad-hoc string.
- Keep API Manager's job (governance, security, monitoring) separate in your head from actually implementing the endpoint logic.
Interview Questions
Is REST a specific technology or a protocol?
Neither, it's an architectural style for designing web APIs, implemented on top of standard HTTP. ColdFusion's REST support is one specific implementation of that style.
Why does resource-based URL design (/users/{id}) matter over action-based URLs (/getUser?id=)?
It keeps the URL structure predictable and centered on what the API actually manages (resources), letting the HTTP method itself carry the action instead of encoding it redundantly into the URL.
What's the difference between building a REST API in ColdFusion and using ColdFusion API Manager?
Building the API (rest="true", access="remote", httpmethod) is done directly in CFML. API Manager is a separate, optional gateway product that sits in front of an already-built API for monitoring, security, and rate-limiting, it doesn't implement the endpoint logic itself.
Summary
In this lesson, you covered what REST actually is as an architectural style, the standard HTTP methods and their conventional meanings, resource-based URL design using a real CRUD example, a first look at ColdFusion's own REST syntax, and the real distinction between building a REST API in CFML versus ColdFusion's separate API Manager product.
What's Next?
The next lesson covers creating REST APIs in ColdFusion for real: the full cfcomponent/restpath/httpmethod/restargsource attributes, and a complete CRUD example.