This document summarizes an agenda for a presentation on advanced ColdBox REST techniques. The presentation covers tools for REST development, best practices for API design including resource naming, documentation, HTTP verbs, status codes, modularity, uniformity, performance through caching, security, and testing APIs through a BDD approach. The presenter is introduced as Luis Majano, founder of Ortus Solutions and creator of ColdBox and other Box frameworks.

1. CBREST2016
Advanced ColdBox RESTTechniques

2. WHO AM I?
• Luis Majano - Computer Engineer
• Born in El Salvador ------------------>
• Architecture + Software Design
• CEO of Ortus Solutions
• Adobe Community Professional
• Creator of all things Box:
ColdBox, ContentBox,WireBox....
www.ortussolutions.com
@ortussolutions
@lmajano

3. AGENDA
• Tools
• Good APITechniques
• Modular API
• Relax Modeling, Documentation
• DocBox Documentation
• BDDTesting
• Security
• Performance

4. TOOLS
• CommandBox
• ColdBox
• Relax Module
• install relax
• Debugger Module
• install cbdebugger
• Good ‘ol curl
• Advanced REST Client

5. A GOOD API OFFERS:
1. Good resource naming
2. Modeling + Documentation
3. HTTPVerb Usage
4. Meaningful Status Codes
5. Scalability
6. Uniformity
7. Performance
8. Security
9. Testability

6. 1. RESOURCE NAMING
• REST = Representational StateTransfer
• An architectural style
• Adhere to best practices
• Resource (URI) centric
• Think of nouns, not verbs (HTTPVerbs)
• Think about plurality and singularity
• Nested resources provide meaning
GET /ticket/12
POST /ticket/12
GET /tickets/12/messages
GET /tickets

7. 2.DOCUMENTATION + MODELING

8. 3.HTTPVERB USAGE
Operation Verb
Create POST
Read GET
Update PUT
Single item update PATCH
Delete DELETE
Info/Metadata HEAD
Resource Doc OPTIONS

9. 4.STATUS CODES
Code Description
200 OK, usually a representation
201 New resource, check headers for URI
202 Accepted (ASYNC), check headers or response for tokens
203 Non-authoritative (Usually a cached response)
204 No Content, but processed
205 Reset Content
206 Partial Results (Usually pagination)

10. 4.MORE STATUS CODES
Code Description
400 Bad Request
401 Unauthorized
402 Payment Required
403 Forbidden
404 Not Found
405 Method not allowed
406 Not acceptable (Validation, invalid data)
408 RequestTimeout
410 Resource Gone
429 Too Many Requests
500 Server Error

11. 5.SCALABILITY : MODULARITY
• ColdBox Modules
• Root api module
• Contains commonalities
• Sub-modules as versions
• v1 - /api/v1
• v2 - /api/v2
• Module Entry Points

12. 6.UNIFORMITY : BASE REST
HANDLER
• Included in ColdBox rest template or
cbrestbasehandler module
• Common Response object
• Tier detection + development headers
• Allowed Methods Security
• Error Handling Commonality
• Security
• Rate Limiting
• Customize it

13. 7. PERFORMANCE : CACHING + GZIP
• Powered by CacheBox
• Multiple cache regions or providers
• Couchbase, Redis, ehCache, etc
• Simple action metadata:
cache, cacheTimeout, cacheLastAccessTimeout
• Supports multi-domain services
• Supports multi-format responses
• Add gzip compression, it goes a long way!

14. 8. SECURITY
• SSL (A must!)
• APITokens
• How?
• cbsecurity Module
• Rule engine
• Inspects incoming routes
• Secure against authentication, permission, roles,
custom.
• Annotation based security
• Base handler can read and verify

15. 9.TESTBOX BDD :TESTABLE
• BDD approach to testing
• Integrates entire application
• Test rendering results
• Test HTTP methods
• Much More