At Stormpath we spent 18 months researching API design best practices. Join Les Hazlewood, Stormpath CTO and Apache Shiro Chair, as he explains how to design a secure REST API, the right way. He'll also hang out for a live Q&A session at the end.
Sign up for Stormpath: https://api.stormpath.com/register
More from Stormpath: http://www.stormpath.com/blog
Les will cover:
REST + JSON API Design
Base URL design tips
API Security
Versioning for APIs
API Resource Formatting
API Return Values and Content Negotiation
API References (Linking)
API Pagination, Parameters, & Errors
Method Overloading
Resource Expansion and Partial Responses
Error Handling
Multi-tenancy
2. @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
29. @lhazlewood @goStormpath
POST as Create
On a parent resource
POST /applications
{
“name”: “Best App Ever”
}
Response:
201 Created
Location: https://api.stormpath.com/applications/a1b2c3
30. @lhazlewood @goStormpath
POST as Update
On instance resource
POST /applications/a1b2c3
{
“name”: “Best App Ever. Srsly.”
}
Response:
200 OK
42. @lhazlewood @goStormpath
HREF
• Distributed Hypermedia is paramount!
• Every accessible Resource has a canonical unique
URL
• Replaces IDs (IDs exist, but are opaque).
• Critical for linking
49. @lhazlewood @goStormpath
Ion meta href
GET /accounts/x7y8z9
200 OK
{
“meta”: { “href”: “https://api.stormpath.com/accounts/x7y8z9” },
“givenName”: “Tony”,
“surname”: “Stark”,
…
}
50. @lhazlewood @goStormpath
Ion link
GET /accounts/x7y8z9
200 OK
{
“meta”: { ... },
“givenName”: “Tony”,
“surname”: “Stark”,
…,
“directory”: {
“meta”:{ “href”: https://api.stormpath.com/directories/g4h5i6” }
}
}
51. @lhazlewood @goStormpath
Ion link (collection)
GET /accounts/x7y8z9
200 OK
{
“meta”: { ... },
“givenName”: “Tony”,
“surname”: “Stark”,
…,
“groups”: {
“meta”: {
“href”: “https://api.stormpath.com/accounts/x7y8z9/groups”, “rel”: [“collection”]
}
}
}
52. @lhazlewood @goStormpath
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)
63. @lhazlewood @goStormpath
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
71. @lhazlewood @goStormpath
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
74. @lhazlewood @goStormpath
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.
76. @lhazlewood @goStormpath
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.
77. @lhazlewood @goStormpath
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!
82. @lhazlewood @goStormpath
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
91. @lhazlewood @goStormpath
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]
94. @lhazlewood @goStormpath
Group to Account
• A group can have many accounts
• An account can be in many groups
• Each mapping is a resource:
GroupMembership
102. @lhazlewood @goStormpath
• 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
109. @lhazlewood @goStormpath
• As descriptive as possible
• As much information as possible
• Developers are your customers
110. @lhazlewood @goStormpath
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”
}
112. @lhazlewood @goStormpath
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
113. @lhazlewood @goStormpath
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!”
114. @lhazlewood @goStormpath
HTTP Authentication Schemes
• Server response to issue challenge:
WWW-Authenticate: <scheme name>
realm=“Application Name”
• Client request to submit credentials:
Authorization: <scheme name> <data>
117. @lhazlewood @goStormpath
• IDs should be opaque
• Should be globally unique
• Avoid sequential numbers (contention, fusking)
• Good candidates: UUIDs, ‘Url64’
126. @lhazlewood @goStormpath
.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