Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Beautiful REST+JSON APIs
Use Computer Audio or Dial In:
Toll-free: 1 877 309 2071
Toll: +1 (909) 259-0034
Access Code: 288...
Format
• 60 Minute Presentation
• 30 Minute Q&A
Please type Questions in the GTW box on
your right for the Q&A
Presenter: Les Hazlewood
Stormpath CTO
PMC Chair, Apache Shiro
@lhazlewood
.com
• User Management and Authentication
API
• Security for your applications
• User security workflows
• Security best p...
Outline
• APIs, REST & JSON
• REST Fundamentals
• Design
Base URL
Versioning
Resource Format
Return Values
Content Negotia...
HATEOAS
• Hypermedia
• As
• The
• Engine
• Of
• Application
• State
Learn more at Stormpath.com
REST Is Easy
Learn more at Stormpath.com
REST Is *&@#$! Hard
(for providers)
Learn more at Stormpath.com
REST can be easy
(if you follow some guidelines)
Learn more at Stormpath.com
Example Domain: Stormpath
• Applications
• Directories
• Accounts
• Groups
• Associations
• Workflows
Learn more at Stormp...
Fundamentals
Learn more at Stormpath.com
Resources
Nouns, not Verbs
Coarse Grained, not Fine Grained
Architectural style for use-case scalability
Learn more at Sto...
What If?
/getAccount
/createDirectory
/updateGroup
/verifyAccountEmailAddress
Learn more at Stormpath.com
What If?
/getAccount
/getAllAccounts
/searchAccounts
/createDirectory
/createLdapDirectory
/updateGroup
/updateGroupName
/...
Keep It Simple
Learn more at Stormpath.com
The Answer
Fundamentally two types of resources:
Collection Resource
Instance Resource
Learn more at Stormpath.com
Collection Resource
/applications
Learn more at Stormpath.com
Instance Resource
/applications/a1b2c3
Learn more at Stormpath.com
Behavior
• GET
• PUT
• POST
• DELETE
• HEAD
Learn more at Stormpath.com
Behavior
POST, GET, PUT, DELETE
≠ 1:1
Create, Read, Update, Delete
Learn more at Stormpath.com
Behavior
As you would expect:
GET = Read
DELETE = Delete
HEAD = Headers, no Body
Learn more at Stormpath.com
Behavior
Not so obvious:
PUT and POST can both be used for
Create and Update
Learn more at Stormpath.com
PUT for Create
Identifier is known by the client:
PUT /applications/clientSpecifiedId
{
…
}
Learn more at Stormpath.com
PUT for Update
Full Replacement
PUT /applications/existingId
{
“name”: “Best App Ever”,
“description”: “Awesomeness”
}
Lea...
PUT
Idempotent
Learn more at Stormpath.com
POST as Create
On a parent resource
POST /applications
{
“name”: “Best App Ever”
}
Response:
201 Created
Location: https:/...
POST as Update
On instance resource
POST /applications/a1b2c3
{
“name”: “Best App Ever. Srsly.”
}
Response:
200 OK
Learn m...
POST
NOT Idempotent
Learn more at Stormpath.com
Media Types
• Format Specification + Parsing Rules
• Request: Accept header
• Response: Content-Type header
• application/...
Design Time!
Learn more at Stormpath.com
Base URL
Learn more at Stormpath.com
http(s)://foo.io
vs
http://www.foo.com/dev/service/api/rest
Learn more at Stormpath.com
http(s)://foo.io
Rest Client
vs
Browser
Learn more at Stormpath.com
Versioning
Learn more at Stormpath.com
URL
https://api.stormpath.com/v1
vs.
Media-Type
application/foo+json;application&v=2
application/foo2+json;application
Lea...
Resource Format
Learn more at Stormpath.com
Media Type
Content-Type: application/json
When time allows:
application/foo+json
application/foo2+json;bar=baz
…
Learn mor...
Media Type
Don’t go overboard!
Media Type != Schema!
Most only need 2 or 3 custom media types:
• instance resource
• colle...
camelCase
‘JS’ in ‘JSON’ = JavaScript
myArray.forEach
Not myArray.for_each
account.givenName
Not account.given_name
Unders...
Date/Time/Timestamp
There’s already a standard. Use it: ISO 8601
Example:
{
…,
“createdAt”: “2013-07-10T18:02:24.343Z”,
.....
createdAt / updatedAt
Learn more at Stormpath.com
createdAt / updatedAt
Most people will want this at some point
{
…,
“createdAt”: “2013-07-10T18:02:24.343Z”,
“updatedAt”: ...
Response Body
Learn more at Stormpath.com
GET obvious
What about POST?
Return the representation in the response
when feasible.
Add override (?_body=false) for cont...
Content Negotiation
Learn more at Stormpath.com
Header
• Accept header
• Header values comma delimited in order
of preference
GET /applications/a1b2c3
Accept: application...
Resource Extension
/applications/a1b2c3.json
/applications/a1b2c3.csv
…
Conventionally overrides Accept header
Learn more ...
HREF
• Distributed Hypermedia is paramount!
• Every accessible Resource has a
canonical unique URL
• Replaces IDs (IDs exi...
Links in JSON
• Tricky in JSON
• XML has it (XLink), JSON doesn’t
• How do we do it?
Learn more at Stormpath.com
Instance w/ HREF
GET /accounts/x7y8z9
200 OK
{
“meta”: {
“href”:“https://api.stormpath.com/v1/accounts/x7y8z9”,
“mediaType...
Resource References
aka ‘Linking’
Learn more at Stormpath.com
Instance Reference
GET /accounts/x7y8z9
200 OK
{
“meta”: {“href”:“...”, ...}
“givenName”: “Tony”,
“surname”: “Stark”,
...,...
Instance Reference
GET /accounts/x7y8z9
200 OK
{
“meta”: { ... },
“givenName”: “Tony”,
“surname”: “Stark”,
…,
“directory”:...
Collection Reference
GET /accounts/x7y8z9
200 OK
{
“meta”: { ... },
“givenName”: “Tony”,
“surname”: “Stark”,
…,
“groups”: ...
Reference Expansion
(aka Entity Expansion, Link Expansion)
Learn more at Stormpath.com
Account and its Directory?
Learn more at Stormpath.com
GET /accounts/x7y8z9?expand=directory
200 OK
{
“meta”: {“href”: “...”,...},
“givenName”: “Tony”,
“surname”: “Stark”,
…,
“d...
Partial Representations
Learn more at Stormpath.com
GET
/accounts/x7y8z9?fields=givenName,surname,
directory(name)
Learn more at Stormpath.com
Collections!
Learn more at Stormpath.com
Collections
• A first class resource ‘citizen’
• Own href / metadata
• Own properties
• Different from all other collectio...
GET /accounts/x7y8z9/groups
200 OK
{
“meta”: { ... },
“offset”: 0,
“limit”: 25,
“size”: 289,
“first”: {“meta”:{“href”:“......
Pagination
Learn more at Stormpath.com
Collection Resource supports query params:
• Offset
• Limit
…/applications?offset=50&limit=25
Learn more at Stormpath.com
GET /accounts/x7y8z9/groups
200 OK
{
“meta”: { ... },
“offset”: 0,
“limit”: 25,
“first”: { “meta”:{“href”: “…/accounts/x7y...
Sorting
Learn more at Stormpath.com
GET .../accounts?
orderBy=surname,givenName%20desc
Learn more at Stormpath.com
Search
Learn more at Stormpath.com
“Find all accounts with a
‘company.com’ email address
that can login to a particular
application”
Learn more at Stormpath....
GET /applications/x7y8z9/accounts?
email=*company.com
200 OK
{
“meta”: { ... },
“offset”: 0,
“limit”: 25,
“first”: { “meta...
Search cont’d
• Filter search
.../accounts?q=some+value
• Attribute Search
.../accounts?surname=Joe&email=*company.c
om
Le...
Search cont’d
• Starts with
?email=joe*
• Ends with
?email=*company.com
• Contains
?email=*foo*
Learn more at Stormpath.com
Search cont’d
• Range queries
“all accounts created between September 1st
and the 15th, inclusive”
.../accounts?createdAt=...
Many To Many
Learn more at Stormpath.com
Group to Account
• A group can have many accounts
• An account can be in many groups
• Each mapping is a resource:
GroupMe...
GET /groupMemberships/23lk3j2j3
200 OK
{
“meta”:{“href”: “.../groupMemberships/23lk3j2j3”},
“account”: {
“meta”:{“href”: “...
GET /accounts/x7y8z9
200 OK
{
“meta”:{“href”: “…/accounts/x7y8z9”},
“givenName”: “Tony”,
“surname”: “Stark”,
…,
“groups”: ...
Async or Long-Lived Operations
Learn more at Stormpath.com
POST /emails
{
“from”: me@somewhere.com,
“subject”: “Hi!”
“body”: “...”
}
Learn more at Stormpath.com
204 Accepted
Location: /emails/23Sd932sSl
{
“status”: “queued”,
...
}
Learn more at Stormpath.com
GET /emails/23Sd932sSl
Expires: 2014-09-29T18:00:00.000Z
{
“status”: “sent”,
...
}
Learn more at Stormpath.com
Batch Operations
Learn more at Stormpath.com
• Each batch reflects a resource
• Batches are likely to be a collection
• Batches are likely to have a status
• Batch del...
Batch Delete
“Delete all company.com accounts”
DELETE /accounts?
email=*@company.com
Learn more at Stormpath.com
Batch Create / Update
Already have a Collection concept. Use it.
Learn more at Stormpath.com
Batch Create or Update
POST /accounts
{
“items”: [
{ ... account 1 ... },
{ ... account 2 ... },
...
]
}
Learn more at Sto...
204 Accepted
Location: /batches/a1b2c3
{
“status”: “processing”, //overall status
“size”: “n”,
“limit”: 25,
...,
“items”: ...
Errors
Learn more at Stormpath.com
• As descriptive as possible
• As much information as possible
• Developers are your customers
Learn more at Stormpath.com
POST /directories
409 Conflict
{
“status”: 409,
“code”: 40924,
“property”: “name”,
“message”: “A Directory named ‘Avengers...
Security
Learn more at Stormpath.com
Avoid sessions when possible
Authenticate every request if necessary
Stateless
Authorize based on resource content, NOT UR...
401 vs 403
• 401 “Unauthorized” really means
Unauthenticated
“You need valid credentials for me to respond to
this request...
HTTP Authentication Schemes
• Server response to issue challenge:
WWW-Authenticate: <scheme name>
realm=“Application Name”...
API Keys
• Entropy
• Password Reset
• Independence
• Scope
• Speed
• Limited Exposure
• Traceability
Learn more at Stormpa...
IDs
Learn more at Stormpath.com
• IDs should be opaque
• Should be globally unique
• Avoid sequential numbers (contention,
fusking)
• Good candidates: UUI...
HTTP Method Overrides
Learn more at Stormpath.com
POST /accounts/x7y8z9?_method=DELETE
Learn more at Stormpath.com
Caching &
Concurrency Control
Learn more at Stormpath.com
Server (initial response):
ETag: "686897696a7c876b7e”
Client (later request):
If-None-Match: "686897696a7c876b7e”
Server (...
Maintenance
Learn more at Stormpath.com
Use HTTP Redirects
Create abstraction layer / endpoints when
migrating
Use well defined custom Media Types
Learn more at S...
• User Management & Authentication
• API Security & Access Management
• Eliminate months of development
• Automatic securi...
Upcoming SlideShare
Loading in …5
×

Elegant Rest Design Webinar

3,128 views

Published on

Companion slides for Stormpath CTO and Co-Founder Les Hazlewood's Elegant REST Design Webinar. This presentation covers all the RESTful best practices learned building the Stormpath APIs. Whether you’re writing your first API, or just need to figure out that last piece of the puzzle, this is a great opportunity to learn more.

Stormpath is a User Management API that reduces development time with instant-on, scalable user infrastructure. Stormpath's intuitive API and expert support make it easy for developers to authenticate, manage and secure users and roles in any application.

  • Be the first to comment

Elegant Rest Design Webinar

  1. 1. Beautiful REST+JSON APIs Use Computer Audio or Dial In: Toll-free: 1 877 309 2071 Toll: +1 (909) 259-0034 Access Code: 288-356-166
  2. 2. Format • 60 Minute Presentation • 30 Minute Q&A Please type Questions in the GTW box on your right for the Q&A
  3. 3. Presenter: Les Hazlewood Stormpath CTO PMC Chair, Apache Shiro @lhazlewood
  4. 4. .com • User Management and Authentication API • Security for your applications • User security workflows • Security best practices • Developer tools, SDKs, libraries Learn more at Stormpath.com
  5. 5. 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 Batch Operations Learn more at Stormpath.com
  6. 6. HATEOAS • Hypermedia • As • The • Engine • Of • Application • State Learn more at Stormpath.com
  7. 7. REST Is Easy Learn more at Stormpath.com
  8. 8. REST Is *&@#$! Hard (for providers) Learn more at Stormpath.com
  9. 9. REST can be easy (if you follow some guidelines) Learn more at Stormpath.com
  10. 10. Example Domain: Stormpath • Applications • Directories • Accounts • Groups • Associations • Workflows Learn more at Stormpath.com
  11. 11. Fundamentals Learn more at Stormpath.com
  12. 12. Resources Nouns, not Verbs Coarse Grained, not Fine Grained Architectural style for use-case scalability Learn more at Stormpath.com
  13. 13. What If? /getAccount /createDirectory /updateGroup /verifyAccountEmailAddress Learn more at Stormpath.com
  14. 14. What If? /getAccount /getAllAccounts /searchAccounts /createDirectory /createLdapDirectory /updateGroup /updateGroupName /findGroupsByDirectory /searchGroupsByName /verifyAccountEmailAddress /verifyAccountEmailAddressByToken … Smells like bad RPC. DON’T DO THIS. Learn more at Stormpath.com
  15. 15. Keep It Simple Learn more at Stormpath.com
  16. 16. The Answer Fundamentally two types of resources: Collection Resource Instance Resource Learn more at Stormpath.com
  17. 17. Collection Resource /applications Learn more at Stormpath.com
  18. 18. Instance Resource /applications/a1b2c3 Learn more at Stormpath.com
  19. 19. Behavior • GET • PUT • POST • DELETE • HEAD Learn more at Stormpath.com
  20. 20. Behavior POST, GET, PUT, DELETE ≠ 1:1 Create, Read, Update, Delete Learn more at Stormpath.com
  21. 21. Behavior As you would expect: GET = Read DELETE = Delete HEAD = Headers, no Body Learn more at Stormpath.com
  22. 22. Behavior Not so obvious: PUT and POST can both be used for Create and Update Learn more at Stormpath.com
  23. 23. PUT for Create Identifier is known by the client: PUT /applications/clientSpecifiedId { … } Learn more at Stormpath.com
  24. 24. PUT for Update Full Replacement PUT /applications/existingId { “name”: “Best App Ever”, “description”: “Awesomeness” } Learn more at Stormpath.com
  25. 25. PUT Idempotent Learn more at Stormpath.com
  26. 26. POST as Create On a parent resource POST /applications { “name”: “Best App Ever” } Response: 201 Created Location: https://api.stormpath.com/applications/a1b2c3 Learn more at Stormpath.com
  27. 27. POST as Update On instance resource POST /applications/a1b2c3 { “name”: “Best App Ever. Srsly.” } Response: 200 OK Learn more at Stormpath.com
  28. 28. POST NOT Idempotent Learn more at Stormpath.com
  29. 29. Media Types • Format Specification + Parsing Rules • Request: Accept header • Response: Content-Type header • application/json • application/foo+json • application/foo+json;application • … Learn more at Stormpath.com
  30. 30. Design Time! Learn more at Stormpath.com
  31. 31. Base URL Learn more at Stormpath.com
  32. 32. http(s)://foo.io vs http://www.foo.com/dev/service/api/rest Learn more at Stormpath.com
  33. 33. http(s)://foo.io Rest Client vs Browser Learn more at Stormpath.com
  34. 34. Versioning Learn more at Stormpath.com
  35. 35. URL https://api.stormpath.com/v1 vs. Media-Type application/foo+json;application&v=2 application/foo2+json;application Learn more at Stormpath.com
  36. 36. Resource Format Learn more at Stormpath.com
  37. 37. Media Type Content-Type: application/json When time allows: application/foo+json application/foo2+json;bar=baz … Learn more at Stormpath.com
  38. 38. Media Type Don’t go overboard! Media Type != Schema! Most only need 2 or 3 custom media types: • instance resource • collection resource application/foo+json application/foo2+json;bar=baz … Learn more at Stormpath.com
  39. 39. 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. Learn more at Stormpath.com
  40. 40. Date/Time/Timestamp There’s already a standard. Use it: ISO 8601 Example: { …, “createdAt”: “2013-07-10T18:02:24.343Z”, ... } Use UTC! Learn more at Stormpath.com
  41. 41. createdAt / updatedAt Learn more at Stormpath.com
  42. 42. 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! Learn more at Stormpath.com
  43. 43. Response Body Learn more at Stormpath.com
  44. 44. GET obvious What about POST? Return the representation in the response when feasible. Add override (?_body=false) for control Learn more at Stormpath.com
  45. 45. Content Negotiation Learn more at Stormpath.com
  46. 46. Header • Accept header • Header values comma delimited in order of preference GET /applications/a1b2c3 Accept: application/json, text/plain Learn more at Stormpath.com
  47. 47. Resource Extension /applications/a1b2c3.json /applications/a1b2c3.csv … Conventionally overrides Accept header Learn more at Stormpath.com
  48. 48. HREF • Distributed Hypermedia is paramount! • Every accessible Resource has a canonical unique URL • Replaces IDs (IDs exist, but are opaque). • Critical for linking Learn more at Stormpath.com
  49. 49. Links in JSON • Tricky in JSON • XML has it (XLink), JSON doesn’t • How do we do it? Learn more at Stormpath.com
  50. 50. Instance w/ HREF GET /accounts/x7y8z9 200 OK { “meta”: { “href”:“https://api.stormpath.com/v1/accounts/x7y8z9”, “mediaType”: “application/json;version=2&schema=...”, ... } “givenName”: “Tony”, “surname”: “Stark”, ... } Learn more at Stormpath.com
  51. 51. Resource References aka ‘Linking’ Learn more at Stormpath.com
  52. 52. Instance Reference GET /accounts/x7y8z9 200 OK { “meta”: {“href”:“...”, ...} “givenName”: “Tony”, “surname”: “Stark”, ..., “directory”: ???? } Learn more at Stormpath.com
  53. 53. Instance Reference GET /accounts/x7y8z9 200 OK { “meta”: { ... }, “givenName”: “Tony”, “surname”: “Stark”, …, “directory”: { “meta”: { “href”: “https://api.stormpath.com/v1/directories/g4h5i6” “mediaType”: “application/json;version=2&schema=...” } } } Learn more at Stormpath.com
  54. 54. Collection Reference GET /accounts/x7y8z9 200 OK { “meta”: { ... }, “givenName”: “Tony”, “surname”: “Stark”, …, “groups”: { “meta”: { “href”: “https://api.stormpath.com/v1/accounts/x7y8z9/groups”, “mediaType”: “application/collection+json;version=2&schema=...” “rel”: [“collection”] } } } Learn more at Stormpath.com
  55. 55. Reference Expansion (aka Entity Expansion, Link Expansion) Learn more at Stormpath.com
  56. 56. Account and its Directory? Learn more at Stormpath.com
  57. 57. GET /accounts/x7y8z9?expand=directory 200 OK { “meta”: {“href”: “...”,...}, “givenName”: “Tony”, “surname”: “Stark”, …, “directory”: { “meta”: {“href”:”...”, ...}, “name”: “Avengers”, “description”: “Hollywood’s hope for more $”, “createdAt”: “2012-07-01T14:22:18.029Z”, … } } Learn more at Stormpath.com
  58. 58. Partial Representations Learn more at Stormpath.com
  59. 59. GET /accounts/x7y8z9?fields=givenName,surname, directory(name) Learn more at Stormpath.com
  60. 60. Collections! Learn more at Stormpath.com
  61. 61. Collections • A first class resource ‘citizen’ • Own href / metadata • Own properties • Different from all other collections Learn more at Stormpath.com
  62. 62. GET /accounts/x7y8z9/groups 200 OK { “meta”: { ... }, “offset”: 0, “limit”: 25, “size”: 289, “first”: {“meta”:{“href”:“.../accounts/x7y8z9/groups?offset=0”}}, “previous”: null, “next”: {“meta”:{“href”:“.../accounts/x7y8z9/groups?offset=25”}}, “last”: {“meta”:{“href”:“...”}}, “items”: [ { “meta”: { “href”:“...”, ...} }, … ] } Learn more at Stormpath.com
  63. 63. Pagination Learn more at Stormpath.com
  64. 64. Collection Resource supports query params: • Offset • Limit …/applications?offset=50&limit=25 Learn more at Stormpath.com
  65. 65. 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”: “…”, ...} }, … ] } Learn more at Stormpath.com
  66. 66. Sorting Learn more at Stormpath.com
  67. 67. GET .../accounts? orderBy=surname,givenName%20desc Learn more at Stormpath.com
  68. 68. Search Learn more at Stormpath.com
  69. 69. “Find all accounts with a ‘company.com’ email address that can login to a particular application” Learn more at Stormpath.com
  70. 70. 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”: “…”, ...} }, … ] } Learn more at Stormpath.com
  71. 71. Search cont’d • Filter search .../accounts?q=some+value • Attribute Search .../accounts?surname=Joe&email=*company.c om Learn more at Stormpath.com
  72. 72. Search cont’d • Starts with ?email=joe* • Ends with ?email=*company.com • Contains ?email=*foo* Learn more at Stormpath.com
  73. 73. Search cont’d • Range queries “all accounts created between September 1st and the 15th, inclusive” .../accounts?createdAt=[2014-09- 01,2014-09-15] Learn more at Stormpath.com
  74. 74. Many To Many Learn more at Stormpath.com
  75. 75. Group to Account • A group can have many accounts • An account can be in many groups • Each mapping is a resource: GroupMembership Learn more at Stormpath.com
  76. 76. GET /groupMemberships/23lk3j2j3 200 OK { “meta”:{“href”: “.../groupMemberships/23lk3j2j3”}, “account”: { “meta”:{“href”: “...”} }, “group”: { “meta”{“href”: “...”} }, … } Learn more at Stormpath.com
  77. 77. GET /accounts/x7y8z9 200 OK { “meta”:{“href”: “…/accounts/x7y8z9”}, “givenName”: “Tony”, “surname”: “Stark”, …, “groups”: { “meta”:{“href”: “…/accounts/x7y8z9/groups”} }, “groupMemberships”: { “meta”:{“href”: “…/groupMemberships?accountId=x7y8z9”} } } Learn more at Stormpath.com
  78. 78. Async or Long-Lived Operations Learn more at Stormpath.com
  79. 79. POST /emails { “from”: me@somewhere.com, “subject”: “Hi!” “body”: “...” } Learn more at Stormpath.com
  80. 80. 204 Accepted Location: /emails/23Sd932sSl { “status”: “queued”, ... } Learn more at Stormpath.com
  81. 81. GET /emails/23Sd932sSl Expires: 2014-09-29T18:00:00.000Z { “status”: “sent”, ... } Learn more at Stormpath.com
  82. 82. Batch Operations Learn more at Stormpath.com
  83. 83. • Each batch reflects a resource • Batches are likely to be a collection • Batches are likely to have a status • Batch deletes easier than create/update Learn more at Stormpath.com
  84. 84. Batch Delete “Delete all company.com accounts” DELETE /accounts? email=*@company.com Learn more at Stormpath.com
  85. 85. Batch Create / Update Already have a Collection concept. Use it. Learn more at Stormpath.com
  86. 86. Batch Create or Update POST /accounts { “items”: [ { ... account 1 ... }, { ... account 2 ... }, ... ] } Learn more at Stormpath.com
  87. 87. 204 Accepted Location: /batches/a1b2c3 { “status”: “processing”, //overall status “size”: “n”, “limit”: 25, ..., “items”: { { response 1 (w/ individual status) ...}, { response 2 (w/ individual status) ...}, ... } } Learn more at Stormpath.com
  88. 88. Errors Learn more at Stormpath.com
  89. 89. • As descriptive as possible • As much information as possible • Developers are your customers Learn more at Stormpath.com
  90. 90. 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/4092 4” } Learn more at Stormpath.com
  91. 91. Security Learn more at Stormpath.com
  92. 92. 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 instead of Username/Passwords Learn more at Stormpath.com
  93. 93. 401 vs 403 • 401 “Unauthorized” really means Unauthenticated “You need valid credentials for me to respond to this request” • 403 “Forbidden” really means Unauthorized “I understood your credentials, but so sorry, you’re not allowed!” Learn more at Stormpath.com
  94. 94. HTTP Authentication Schemes • Server response to issue challenge: WWW-Authenticate: <scheme name> realm=“Application Name” • Client request to submit credentials: Authorization: <scheme name> <data> Learn more at Stormpath.com
  95. 95. API Keys • Entropy • Password Reset • Independence • Scope • Speed • Limited Exposure • Traceability Learn more at Stormpath.com
  96. 96. IDs Learn more at Stormpath.com
  97. 97. • IDs should be opaque • Should be globally unique • Avoid sequential numbers (contention, fusking) • Good candidates: UUIDs, ‘Url64’ Learn more at Stormpath.com
  98. 98. HTTP Method Overrides Learn more at Stormpath.com
  99. 99. POST /accounts/x7y8z9?_method=DELETE Learn more at Stormpath.com
  100. 100. Caching & Concurrency Control Learn more at Stormpath.com
  101. 101. Server (initial response): ETag: "686897696a7c876b7e” Client (later request): If-None-Match: "686897696a7c876b7e” Server (later response): 304 Not Modified Learn more at Stormpath.com
  102. 102. Maintenance Learn more at Stormpath.com
  103. 103. Use HTTP Redirects Create abstraction layer / endpoints when migrating Use well defined custom Media Types Learn more at Stormpath.com
  104. 104. • User Management & Authentication • API Security & Access Management • Eliminate months of development • Automatic security best practices Coming Soon! Loopback support

×