Beautiful REST+JSON APIs with Ion

Beautiful REST+JSON APIs
with Ion
Les Hazlewood @lhazlewood
CTO, Stormpath, stormpath.com

@lhazlewood @goStormpath
.com
• User Management API for Developers
• Password security
• Authentication and Authorization
• LDAP/AD/Social/SAML/OAuth support
• Instant-on, scalable, and highly available
• Free for developers

Why REST?
• Scalability
• Generality
• Independence
• Latency (Caching)
• Security
• Encapsulation

Why JSON?
• Ubiquity
• Simplicity
• Readability
• Scalability
• Flexibility

REST Is Easy

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

JSON – No Spec

REST can be easy
(if you follow some guidelines)

HATEOAS
• Hypermedia
• As
• The
• Engine
• Of
• Application
• State

HATEOAS
• Links
• State Transitions

Fielding’s Requirements
roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-
driven:
• Communication Protocol Independent
• Media Type Centric
• No Fixed Names / Hierarchies
• Dynamically Typed!
• ZERO OUT-OF-BAND KNOWLEDGE

How do we meet these
requirements?

How do we...?
Base URL
Versioning
Resource Format
Return Values
Content Negotiation
References (Linking)
Pagination
Query Parameters
Create/Update
Search
Associations
Errors
IDs
Method Overloading
Resource Expansion
Partial Responses
Caching & Etags
Security
Multi Tenancy
Maintenance
Batch Operations

Fundamentals

Resources
Nouns, not Verbs
Coarse Grained, not Fine Grained
Architectural style for use-case scalability

What If?
/getAccount
/createDirectory
/updateGroup
/verifyAccountEmailAddress

What If?
/getAccount
/getAllAccounts
/searchAccounts
/createDirectory
/createLdapDirectory
/updateGroup
/updateGroupName
/findGroupsByDirectory
/searchGroupsByName
/verifyAccountEmailAddress
/verifyAccountEmailAddressByToken
…
Smells like bad RPC. DON’T DO THIS.

Keep It Simple

The Answer
Fundamentally two types of resources:
Collection Resource
Instance Resource

Collection Resource
/applications

Instance Resource
/applications/a1b2c3

Behavior
• GET
• PUT
• POST
• DELETE
• HEAD

Behavior
POST, GET, PUT, DELETE
≠ 1:1
Create, Read, Update, Delete

Behavior
As you would expect:
GET = Read
DELETE = Delete
HEAD = Headers, no Body

Behavior
Not so obvious:
PUT and POST can both be used for
Create and Update

PUT for Create
Identifier is known by the client:
PUT /applications/clientSpecifiedId
{
…
}

PUT for Update
Full Replacement
PUT /applications/existingId
{
“name”: “Best App Ever”,
“description”: “Awesomeness”
}

PUT
Idempotent

POST as Create
On a parent resource
POST /applications
{
“name”: “Best App Ever”
}
Response:
201 Created
Location: https://api.stormpath.com/applications/a1b2c3

POST as Update
On instance resource
POST /applications/a1b2c3
{
“name”: “Best App Ever. Srsly.”
}
Response:
200 OK

POST
NOT Idempotent

Media Types
• Format Specification + Parsing Rules
• Request: Accept header
• Response: Content-Type header
• application/json
• application/ion+json
• application/ion+json;v=2
• …

Design Time!

HATEAOS in JSON: Ion

Resources

Object
{
“firstName”: “Bob”,
“lastName”: “Smith”,
“birthDate”: “1980-01-23”,
}

Ion Object
{
“meta”: { ... },
“firstName”: “Bob”,
“lastName”: “Smith”,
“birthDate”: “1980-01-23”,
}

Naïve collection (not recommended)
“items”: []

Collection Object
{
“items”: []
}

Ion Collection
{
“meta”: { ... },
“items”: []
}

Linking

HREF
• Distributed Hypermedia is paramount!
• Every accessible Resource has a canonical unique
URL
• Replaces IDs (IDs exist, but are opaque).
• Critical for linking

Linking in JSON?
• XML has it (XLink), JSON doesn’t
• How do we do it?

Naïve linking

Naïve linking - instance
GET /accounts/x7y8z9
200 OK
{
“givenName”: “Tony”,
“surname”: “Stark”,
…,
“directory”: ????
}

Naïve linking - instance cont’d
200 OK
{
…,
“directory”: {
“href”: “https://api.stormpath.com/v1/directories/g4h5i6”
}
}

Naïve linking - collection
200 OK
{
…,
“groups”: {
“href”: “https://api.stormpath.com/accounts/x7y8z9/groups”
}
}

Ion linking (recommended)

Ion meta href
200 OK
{
“meta”: { “href”: “https://api.stormpath.com/accounts/x7y8z9” },
…
}

Ion link
200 OK
{
“meta”: { ... },
…,
“directory”: {
“meta”:{ “href”: https://api.stormpath.com/directories/g4h5i6” }
}
}

Ion link (collection)
200 OK
{
“meta”: { ... },
…,
“groups”: {
“meta”: {
“href”: “https://api.stormpath.com/accounts/x7y8z9/groups”, “rel”: [“collection”]
}
}
}

What about HAL?
• Linking focus
• Forces links to be separate from context/content
– (when was the last time you had to put all of your anchors at
the bottom of an html paragraph? Right... never.)
• In contrast to HAL, Ion is much more like HTML – it’s all in
one convenient spec.
• Ion transliteration to/from HTML is far easier (by design)

State Transitions

Creating And Updating

Remember HATEOS?

“Let me go read the docs to figure
out how to POST”

NO! This is not HATEOS.

How do browsers work?

Forms

Forms: Create
{
“foo”: “bar”,
“baz”: “boo”,
...
“createAccount”: {
“meta”: {“href”: “https://foo.io/users”, “rel”: [“create-form”], “method”: “POST”},
“items”: [
{“name”: “login”, “required”: “true”, “label”: “Username or Email” },
{“name”: “password”, “secret”: “true”, “required”: “true”, “label”: “Password”}
]
}
}

Forms: Create cont’d
{
"meta": {"href": "https://example.io/users", "rel":["create-form"], "method":"POST"},
"items": [
{"name":"username"},
{"name": "password", "secret": true },
{"name": "visitedContinents","type": "set", "minitems": 1,"maxitems": 7,"options": {
"items": [
{"label": "Africa", "value": "af" },
{"label": "North America", "value": "na" },
{"label": "South America", "value": "sa" },
{"label": "Europe", "value": "eu" },
{"label": "Asia", "value": "as" },
{"label": "Oceania", "value": "oc" },
{"label": "Antarctica", "value": "an" },
]
}
}
]
}

Forms: Search / Query{
...
“findAccounts”: {
“meta”: { “href”: “https://foo.io/users”, “rel”: [“search-form”], “method”: “GET” },
“items”: [
{“name”: “username”, “label”: “Username”},
{“name”: “email”, “type”: “email”, “label”: “Email” },
{“name”: “givenName”, “label”: “First Name” },
{“name”: “surname”, “label”: “Last Name”},
]
}
}

What about Schemas / json-schema ?
Not needed. REST != RDBMS
(are schemas necessary for browsers/HTML?)
Forms do the same thing and are more flexible/powerful
Remember Fielding’s REST Rule about Dynamic Typing

HTTP Protocol Semantics

Base URL

http(s)://foo.io
vs
http://www.foo.com/dev/service/api/rest

http(s)://foo.io
Rest Client
vs
Browser

Versioning

URL
https://api.stormpath.com/v1
vs.
Media-Type
application/json
application/ion+json

Content Negotiation

Header
• Accept header
• Header values comma delimited
• q param determines precedence, defaults to 1, then
conventionally by list order
GET /applications/a1b2c3
Accept: application/json, text/plain;q=0.8

Resource Extension
/applications/a1b2c3.json
/applications/a1b2c3.csv
…
Conventionally overrides Accept header

Style Guide

camelCase
‘JS’ in ‘JSON’ = JavaScript
myArray.forEach
Not myArray.for_each
account.givenName
Not account.given_name
Underscores for property/function names are unconventional
for JS. Stay consistent.

Dates & Times

Dates & Times
There’s already a standard. Use it: ISO 8601
“createdAt”: “2013-07-10T18:02:24.343Z”
Use UTC!
This is represented in Ion as a field types of date, time,
datetime, etc.

createdAt / updatedAt
Most people will want this at some point
{
…,
“createdAt”: “2013-07-10T18:02:24.343Z”,
“updatedAt”: “2014-09-29T07:02:48.761Z”
}
Use UTC!

Reference Expansion
(aka Entity Expansion, Link Expansion)

Account and its Directory?

GET /accounts/x7y8z9?expand=directory
200 OK
{
“meta”: {..., “expandable”: [“directory”,...] },
…,
“directory”: {
“meta”: { ... },
“name”: “Avengers”,
“description”: “Hollywood’s plan for more $”,
“createdAt”: “2012-07-01T14:22:18.029Z”,
…
}
}

Collection Pagination

Ensure Collection Resources support query params:
• Offset + Limit vs Cursor
…/applications?offset=50&limit=25
• Don’t require the user to query for these – provide OOTB links

GET /accounts/x7y8z9/groups
200 OK
{
“meta”: { ... },
“offset”: 0,
“limit”: 25,
“first”: { “meta”:{“href”: “…/accounts/x7y8z9/groups?offset=0”}},
“previous”: null,
“next”: { “meta”:{“href”: “…/accounts/x7y8z9/groups?offset=25”}},
“last”: { “meta”:{“href”: “…”}},
“items”: [
{
“meta”: { “href”: “…”, ...}
},
{
“meta”: { “href”: “…”, ...}
},
…
]
}

Sorting

GET .../accounts?
orderBy=surname,givenName%20desc

Search

“Find all accounts with a
‘company.com’ email address
that can login to a particular
application”

GET /applications/x7y8z9/accounts?email=*company.com
200 OK
{
“meta”: { ... },
“offset”: 0,
“limit”: 25,
“first”: { “meta”:{
“href”:“/applications/x7y8z9/accounts?email=*company.com&offset=0”}
},
“previous”: null,
“next”: { “meta”:{
“href”: “/applications/x7y8z9/accounts?email=*company.com&offset=25”}
},
“last”: { “meta”:{“href”: “…”}},
“items”: [
{ “meta”: { “href”: “…”, ...} },
{ “meta”: { “href”: “…”, ...} },
…
]
}

Search cont’d
• Filter search
.../accounts?q=some+value
• Attribute Search
.../accounts?surname=Joe&email=*company.com

Search cont’d
• Starts with
?email=joe*
• Ends with
?email=*company.com
• Contains (warning! Bad performance)
?email=*foo*

Search cont’d
• Range queries via Ion min and max field members
“all accounts created between September 1st and the 15th”
Form fields example:
{“name”: “createdAtBegin”, “min”: “2014-01-01”,”max=“2014-12-31”}
{“name”: “createdAtEnd”, “min”: “2014-01-01”,”max=“2014-12-31”}
Ion TBD: range type:
.../accounts?createdAt=[2014-09-01,2014-09-15]

Search cont’d
• Use Ion forms and the pattern form field member to
represent search expressions

Many To Many

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

GET /groupMemberships/23lk3j2j3
200 OK
{
“meta”:{“href”: “…/groupMemberships/23lk3j2j3”},
“account”: {
“meta”:{“href”: “…”}
},
“group”: {
“meta”{“href”: “…”}
},
…
}

200 OK
{
“meta”:{“href”: “…/accounts/x7y8z9”},
…,
“groups”: {
“meta”:{“href”: “…/accounts/x7y8z9/groups” “rel”: [“collection”]}
},
“groupMemberships”: {
“meta”:{“href”: “…/groupMemberships?accountId=x7y8z9”,”rel”:[“collection”]}
}
}

Async or Long-Lived Operations

POST /emails
{
“from”: me@somewhere.com,
“subject”: “Hi!”
“body”: “...”
}

204 Accepted
Location: /emails/23Sd932sSl
{
“status”: “queued”,
...
}

GET /emails/23Sd932sSl
Expires: 2014-09-29T18:00:00.000Z
{
“status”: “sent”,
...
}

Batch Operations

• Each batch is represented as a resource
• Batches are likely to be a collection
• Batches are likely to have a status
• Downside: problematic regarding HTTP caching

Batch Delete
“Delete all company.com accounts”
DELETE /accounts?
email=*@company.com

Batch Create / Update
Already have a Collection concept. Use it.

Batch Create or Update
POST /accounts
{
“meta”: { ... },
“items”: [
{ ... account 1 ... },
{ ... account 2 ... },
...
]
}

Batch Operations: The ‘Catch’
HTTP Caching is bypassed entirely 

204 Accepted
Location: /batches/a1b2c3
{
“status”: “processing”, //overall status
“size”: “n”,
“limit”: 25,
...,
“items”: {
{ response 1 (w/ individual status) ...},
{ response 2 (w/ individual status) ...},
...
}
}

Errors

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

POST /directories
409 Conflict
{
“status”: 409,
“code”: 40924,
“property”: “name”,
“message”: “A Directory named ‘Avengers’ already exists.”,
“developerMessage”: “A directory named ‘Avengers’ already
exists. If you have a stale local cache, please expire it
now.”,
“moreInfo”: “https://www.stormpath.com/docs/api/errors/40924”
}

Security

Avoid sessions when possible
Authenticate every request if necessary
Stateless
Authorize based on resource content, NOT URL!
Use Existing Protocol:
Oauth 1.0a, Oauth2, Basic over SSL only
Custom Authentication Scheme:
Only if you provide client code / SDK
Only if you really, really know what you’re doing
Use API Keys and/or JWTs instead of Username/Passwords

401 vs 403
• 401 “Unauthorized” really means Unauthenticated
“You need valid credentials for me to respond to this request”
• 403 “Forbidden” really means Unauthorized
“Sorry, you’re not allowed!”

HTTP Authentication Schemes
• Server response to issue challenge:
WWW-Authenticate: <scheme name>
realm=“Application Name”
• Client request to submit credentials:
Authorization: <scheme name> <data>

API Keys
• Entropy
• Password Reset
• Independence
• Scope
• Speed
• Limited Exposure
• Traceability

• IDs should be opaque
• Should be globally unique
• Avoid sequential numbers (contention, fusking)
• Good candidates: UUIDs, ‘Url64’

HTTP Method Overrides

POST /accounts/x7y8z9?_method=DELETE

Caching &
Concurrency Control

Server (initial response):
ETag: "686897696a7c876b7e”
Client (later request):
If-None-Match: "686897696a7c876b7e”
Server (later response):
304 Not Modified

Maintenance

Use HTTP Redirects
Create abstraction layer / endpoints when migrating
Use well defined custom Media Types

IETF RFC?

Ion Media Type
ionwg.org/draft-ion.html

.com
• Free for developers
• Eliminate months of development
• Automatic security best practices
• Single Sign On
• Social/OAuth/SAML/Multi-factor/etc
• API Authentication & Key Management
• Token Authentication for SPAs / Mobile
• Authorization & Multi-tenancy for your apps
Libraries and integrations:
https://docs.stormpath.com

Beautiful REST+JSON APIs with Ion

More Related Content

What's hot (20)

Viewers also liked (20)

Similar to Beautiful REST+JSON APIs with Ion (20)

More from Stormpath (10)

Recently uploaded (20)

Beautiful REST+JSON APIs with Ion