Come discover what in the world are RESTFul services and what are its benefits over other API building technologies. We will cover the basics of HTTP representation protocols, RESTful routing, security, authentication and testing. We will then move to modeling RESTful resources via an open source tool called Relax; Restful Tools For Lazy Experts and finally scaling it with the Adobe API Manager.
13. 1. Resource Naming
1. URI Centric
2. Use nouns, avoid verbs (HTTPVerbs)
3. Deeper you go in the resource the more detail
4. URL Params (Options)
5. Headers (Auth+Options)
6. This is where a modeling tool can help
/customers
Get - List customers
Post - Create new customer
/customer/:id
Get - Show customer
Put - Update customer
Delete - Delete customer
/customer/:id/invoices
Get - All invoices
Post - Create invoice
/customer/:id/invoice/:invoiceID
Get - Show invoice
Put - Update invoice
Delete -Delete invoice
14. 2. HTTP Verb Usage
Operation Verb
Create POST
Read GET
Update PUT
Single item update PATCH
Delete DELETE
Info/Metadata HEAD
Resource Doc OPTIONS
15. 3. Meaningful 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)
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
18. RELAX MODEL
function configure(){
// This is where we define our RESTful service, this is usually
// our first place before even building it, we spec it out.
this.relax = {
// Service Title
title = "ForgeBox IO",
// Service Description
description = "This API powers ForgeBox",
// Service entry point, can be a single string or name value pairs to denote tiers
//entryPoint = "http://www.myapi.com",
entryPoint = {
dev = "http://localhost:9095/api/v1",
stg = "http://forgebox.stg.ortussolutions.com/api/v1",
prd = "http://forgebox.io/api/v1"
},
// Does it have extension detection via ColdBox
extensionDetection = true,
// Valid format extensions
validExtensions = "json",
// Does it throw exceptions when invalid extensions are detected
throwOnInvalidExtension = false
};
// Global API Headers
// globalHeader( name="x-app-token", description="The secret application token", required=true, type="string" );
19. 5.Uniformity
• Common Response object
• Common Controller (MVC)
• HTTPVerb Security
• Access Security
• Error Handling Uniformity
• Response Uniformity
Error!
Security
Where Frameworks Will Help!
21. BASE CONTROLLER/**
* Around handler for all functions
*/
function aroundHandler( event, rc, prc, targetAction, eventArguments ){
try{
var stime = getTickCount();
// prepare our response object
prc.response = getModel( "Response@core" );
// Scope the incoming user request
prc.oCurrentUser = securityService.getUserSession();
// prepare argument execution
var args = { event = arguments.event, rc = arguments.rc, prc = arguments.prc };
structAppend( args, arguments.eventArguments );
// Secure the call
if( isAuthorized( event, rc, prc, targetAction ) ){
// Execute action
var simpleResults = arguments.targetAction( argumentCollection=args );
}
} catch( Any e ){
// Log Locally
log.error( "Error calling #event.getCurrentEvent()#: #e.message# #e.detail#", e );
// Log to BugLogHQ
22. 6. SECURITY
SSL
HTTP Verb Security
Request Throttling
Client API Keys or Tokens (Headers/Params)
API Key + Secret Encryption Keys (Like Amazon)
Basic Authentication (At least its something!)
IP Based Filtering/Tagging (Programmatic/Firewall/Etc)
oAuth
Adobe API Manager
23. • Upgrade/Downgrade Paths
• Scale
• No more monoliths
• Implementations:
• Frameworks
• Adobe API Manager
• Both
7. VERSIONING (MODULARITY)