building advanced restful services

CBREST2016Advanced ColdBox REST Techniques

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

AGENDA• Tools• Good API Techniques• Modular API• Relax Modeling, Documentation• DocBox Documentation• BDD Testing• Security• Performance

TOOLS• CommandBox• ColdBox• Relax Module

• install relax• Debugger Module

• install cbdebugger• Good ‘ol curl • Advanced REST Client

A GOOD API OFFERS:1. Good resource naming2. Modeling + Documentation 3. HTTP Verb Usage4. Meaningful Status Codes5. Scalability6. Uniformity7. Performance8. Security9. Testability

1. RESOURCE NAMING• REST = Representational State Transfer• An architectural style• Adhere to best practices• Resource (URI) centric• Think of nouns, not verbs (HTTP Verbs)• Think about plurality and singularity• Nested resources provide meaning

GET /ticket/12 POST /ticket/12

GET /tickets/12/messages GET /tickets

2.DOCUMENTATION + MODELING

3.HTTP VERB USAGEOperation Verb

Create POST

Read GET

Update PUT

Single item update PATCH

Delete DELETE

Info/Metadata HEAD

Resource Doc OPTIONS

4.STATUS CODESCode 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)

4.MORE STATUS CODESCode Description400 Bad Request401 Unauthorized402 Payment Required403 Forbidden404 Not Found405 Method not allowed406 Not acceptable (Validation, invalid data)408 Request Timeout410 Resource Gone429 Too Many Requests500 Server Error

5.SCALABILITY : MODULARITY

• ColdBox Modules• Root api module

• Contains commonalities• Sub-modules as versions

• v1 - /api/v1• v2 - /api/v2

• Module Entry Points

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

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!

8. SECURITY• SSL (A must!)• API Tokens• How?

• cbsecurity Module• Rule engine• Inspects incoming routes• Secure against authentication, permission, roles,

custom.• Annotation based security

• Base handler can read and verify

9. TESTBOX BDD : TESTABLE

• BDD approach to testing• Integrates entire application• Test rendering results• Test HTTP methods• Much More