restjsonapis-120711135859-phpapp02

7/28/2019 restjsonapis-120711135859-phpapp02

1/77

Beautiful REST + JSON APIs

Les Hazlewood

CTO, Stormpath

stormpath.com


2/77

About

CTO Co-Founder StormpathIdentity and Access Management APIUser security automations (e.g.

authentication, password reset)

Active Directory for the cloudon steroids

Founder, PMC Chair, Apache ShiroLeading Java Security Framework+200k downloads


3/77

Outline

APIs, REST & JSON REST Fundamentals Design:

Base URL Versioning Resource Format

Return Values Content Negotiation References (Linking) Pagination Query Parameters Associations Errors IDs Method Overloading

Resource Expansion Partial Responses Caching & Etags Security Multi Tenancy Maintenance


4/77

APIs

Applications Developers Pragmatism over Ideology Adoption Scale


5/77

Why REST?

Scalability Generality Independence Latency (Caching) Security Encapsulation


6/77

Why JSON?

Ubiquity Simplicity Readability Scalability Flexibility


7/77

HATEOAS

Hypermedia As The Engine Of Application StateFurther restriction on REST architectures.


8/77

REST Is Easy


9/77

REST Is *&@#$! Hard(for providers)


10/77

REST can be easy

(if you follow some guidelines)


11/77

Fundamentals


12/77


13/77

Resources

Nouns, not Verbs

Coarse Grained, not Fine Grained

Architectural style for use-case scalability


14/77

/getAccount

/createDirectory

/updateGroup

/verifyAccountEmailAddress

What If?


15/77

/getAccount/getAllAccounts/searchAccounts/createDirectory

/createLdapDirectory/updateGroup/updateGroupName/findGroupsByDirectory/searchGroupsByName

/verifyAccountEmailAddress/verifyAccountEmailAddressByTokenSmells like bad RPC. DONT DO THIS.

What If?


16/77

Keep It Simple


17/77

The Answer

Fundamentally two types of resources:

Collection Resource

Instance Resource


18/77

Collection Resource

/applications


19/77

Instance Resource

/applications/a1b2c3


20/77

Behavior

GETPUTPOSTDELETEHEAD


21/77

Behavior

POST, GET, PUT, DELETE

1:1Create,Read,Update,Delete


22/77

Behavior

Asyouwouldexpect:

GET=Read

DELETE=Delete

HEAD=Headers,noBody


23/77

Behavior

Notsoobvious:

PUTandPOSTcanbothbeusedfor

CreateandUpdate


24/77

PUT for Create

Idenfierisknownbytheclient:

PUT /applications/clientSpecifiedId

{

}


25/77

PUT for Update

FullReplacement

PUT /applications/existingId{

name: Best App Ever,

description: Awesomeness

}


26/77

PUT

Idempotent


27/77

POST as CreateOnaparentresource

POST /applications

{name: Best App Ever

}

Response:

201 Created

Location: https://api.stormpath.com/applications/a1b2c3


28/77

POST as UpdateOninstanceresource

POST /applications/a1b2c3

{name: Best App Ever. Srsly.

}

Response:

200 OK


29/77

POST

NOTIdempotent


30/77

Media Types

FormatSpecificaon+ParsingRules Request:Acceptheader Response:Content-Typeheader application/json application/foo+json application/foo+json;application


31/77

Design Time!


32/77

Base URL


33/77

http(s)://api.foo.com

vs

http://www.foo.com/dev/service/api/rest


34/77

http(s)://api.foo.com

Rest Clientvs

Browser


35/77

Versioning


36/77

URL

https://api.stormpath.com/v1

vs.

Media-Typeapplication/json+foo;application,v=1


37/77

Resource Format


38/77

Media Type

Content-Type: application/json

When time allows:

application/foo+json

application/foo+json;bar=baz,v=1


39/77

camelCase

JS in JSON = JavaScript

myArray.forEach

NotmyArray.for_each

account.givenName

Notaccount.given_name

Underscores for property/function namesare unconventional for JS. Stay consistent.


40/77

Date/Time/Timestamp

Theres already a standard. Use it: ISO 8601

Example:

{

,

createdTimestamp: 2012-07-10T18:02:24.343Z

}

Use UTC!


41/77

HREF

Distributed Hypermedia is paramount! Every accessible Resource has a unique

URL. Replaces IDs (IDs exist, but are opaque).{href: https://api.stormpath.com/v1/accounts/x7y8z9,

}

Critical for linking, as well soon see


42/77

Response Body


43/77

GET obvious

What about POST?

Return the representation in the responsewhen feasible.

Add override (?_body=false) for control


44/77

Content Negotiation


45/77

Header

Accept header Header values comma delimited inorder of preferenceGET /applications/a1b2c3

Accept: application/json, text/plain


46/77

Resource Extension

/applications/a1b2c3.json

/applications/a1b2c3.csv

ConvenonallyoverridesAcceptheader


47/77

Resource Referencesaka Linking


48/77

Hypermedia is paramount. Linking is fundamental to scalability. Tricky in JSON XML has it (XLink), JSON doesnt How do we do it?


49/77

Instance Reference

GET /accounts/x7y8z9

200 OK

{

href: https://api.stormpath.com/v1/accounts/x7y8z9,

givenName: Tony,

surname: Stark,

,

directory: ????}


50/77

Instance Reference


200 OK

{


givenName: Tony,

surname: Stark,

,

directory: {href: https://api.stormpath.com/v1/directories/g4h5i6

}

}


51/77

Collection Reference


200 OK

{


givenName: Tony,

surname: Stark,

,

groups: {

href: https://api.stormpath.com/v1/accounts/x7y8z9/groups

}

}


52/77

Reference Expansion

(aka Entity Expansion, Link Expansion)


53/77

Account and its Directory?


54/77

GET /accounts/x7y8z9?expand=directory

200 OK

{


givenName: Tony,

surname: Stark,

,directory: {

href: https://api.stormpath.com/v1/directories/g4h5i6,

name: Avengers,

creationDate: 2012-07-01T14:22:18.029Z,

}

}


55/77

Partial Representations


56/77

GET /accounts/x7y8z9?fields=givenName,surname,directory(name)


57/77

Pagination


58/77

Collection Resource supports queryparams:

Off

set Limit/applications?offset=50&limit=25


59/77

GET /accounts/x7y8z9/groups

200 OK

{href: /accounts/x7y8z9/groups,offset: 0,

limit: 25,first: { href: /accounts/x7y8z9/groups?offset=0 },previous: null,

next: { href: /accounts/x7y8z9/groups?offset=25 },

last: { href: },items: [{href:

},{

href:

},

]}


60/77

Many To Many


61/77

Group to Account

A group can have many accounts An account can be in many groups Each mapping is a resource:GroupMembership


62/77

GET /groupMemberships/23lk3j2j3

200 OK

{

href: /groupMemberships/23lk3j2j3,

account: {

href:

},group: {

href:

},

}


63/77


200 OK

{

href: /accounts/x7y8z9,

givenName: Tony,

surname: Stark,

,groupMemberships: {

href: /groupMemberships?accountId=x7y8z9

}

}


64/77

Errors


65/77

As descriptive as possible As much information as possible Developers are your customers


66/77

POST /directories

409 Conflict{status: 409,

code: 40924,

property: name,

message: A Directory named Avengersalready exists.,

developerMessage: A directory namedAvengers already exists. If you have a stalelocal cache, please expire it now.,

moreInfo: https://www.stormpath.com/docs/api/errors/40924

}


67/77

IDs


68/77

IDs should be opaque Should be globally unique

Avoid sequential numbers (contention) Good candidates: UUIDs, Url64


69/77


70/77

POST /accounts/x7y8z9?_method=DELETE


71/77

Caching &Concurrency Control


72/77

Server(inialresponse):

ETag: "686897696a7c876b7e

Client(laterrequest):

If-None-Match: "686897696a7c876b7e

Server(laterresponse):

304 Not Modified


73/77

Security


74/77

Avoid sessions when possibleAuthenticate every request if necessaryStateless

Authorize based on resource content, NOT URL!

Use Existing Protocol:Oauth 1.0a, Oauth2, Basic over SSL only

Use Custom Scheme:Only if you provide client code / SDKOnly if you really, reallyknow what youre doing


75/77

Maintenance


76/77

Use HTTP Redirects

Create abstraction layer / endpoints whenmigrating

Use well defined custom Media Types


77/77

Thanks!

Check out Stormpath.com/Docs forreferences and examples

Sign up at Stormpath.com Follow us on @goStormpath

restjsonapis-120711135859-phpapp02

Documents