elegant rest design webinar
TRANSCRIPT
![Page 1: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/1.jpg)
Beautiful REST+JSON APIs
Use Computer Audio or Dial In:
Toll-free: 1 877 309 2071Toll: +1 (909) 259-0034
Access Code: 288-356-166
![Page 2: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/2.jpg)
Format
• 60 Minute Presentation
• 30 Minute Q&A
Please type Questions in the GTW box on
your right for the Q&A
![Page 3: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/3.jpg)
Presenter: Les Hazlewood
Stormpath CTO
PMC Chair, Apache Shiro
@lhazlewood
![Page 4: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/4.jpg)
.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
![Page 5: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/5.jpg)
Outline• APIs, REST & JSON
• REST Fundamentals
• Design
Base URLVersioningResource FormatReturn ValuesContent NegotiationReferences (Linking)PaginationQuery ParametersAssociations
ErrorsIDsMethod OverloadingResource ExpansionPartial ResponsesCaching & EtagsSecurityMulti TenancyMaintenanceBatch Operations
Learn more at Stormpath.com
![Page 6: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/6.jpg)
HATEOAS
• Hypermedia
• As
• The
• Engine
• Of
• Application
• State
Learn more at Stormpath.com
![Page 7: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/7.jpg)
REST Is Easy
Learn more at Stormpath.com
![Page 8: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/8.jpg)
REST Is *&@#$! Hard(for providers)
Learn more at Stormpath.com
![Page 9: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/9.jpg)
REST can be easy
(if you follow some guidelines)
Learn more at Stormpath.com
![Page 10: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/10.jpg)
Example Domain: Stormpath
• Applications
• Directories
• Accounts
• Groups
• Associations
• Workflows
Learn more at Stormpath.com
![Page 11: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/11.jpg)
Fundamentals
Learn more at Stormpath.com
![Page 12: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/12.jpg)
Resources
Nouns, not Verbs
Coarse Grained, not Fine Grained
Architectural style for use-case scalability
Learn more at Stormpath.com
![Page 13: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/13.jpg)
What If?
/getAccount
/createDirectory
/updateGroup
/verifyAccountEmailAddress
Learn more at Stormpath.com
![Page 14: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/14.jpg)
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
![Page 15: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/15.jpg)
Keep It Simple
Learn more at Stormpath.com
![Page 16: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/16.jpg)
The Answer
Fundamentally two types of resources:
Collection Resource
Instance Resource
Learn more at Stormpath.com
![Page 17: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/17.jpg)
Collection Resource
/applications
Learn more at Stormpath.com
![Page 18: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/18.jpg)
Instance Resource
/applications/a1b2c3
Learn more at Stormpath.com
![Page 19: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/19.jpg)
Behavior
• GET
• PUT
• POST
• DELETE
• HEAD
Learn more at Stormpath.com
![Page 20: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/20.jpg)
Behavior
POST, GET, PUT, DELETE
≠ 1:1Create, Read, Update, Delete
Learn more at Stormpath.com
![Page 21: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/21.jpg)
Behavior
As you would expect:
GET = Read
DELETE = Delete
HEAD = Headers, no Body
Learn more at Stormpath.com
![Page 22: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/22.jpg)
Behavior
Not so obvious:
PUT and POST can both be used for
Create and Update
Learn more at Stormpath.com
![Page 23: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/23.jpg)
PUT for Create
Identifier is known by the client:
PUT /applications/clientSpecifiedId
{
…
}
Learn more at Stormpath.com
![Page 24: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/24.jpg)
PUT for Update
Full Replacement
PUT /applications/existingId
{
“name”: “Best App Ever”,
“description”: “Awesomeness”
}
Learn more at Stormpath.com
![Page 25: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/25.jpg)
PUT
Idempotent
Learn more at Stormpath.com
![Page 26: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/26.jpg)
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
![Page 27: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/27.jpg)
POST as Update
On instance resource
POST /applications/a1b2c3
{
“name”: “Best App Ever. Srsly.”
}
Response:
200 OK
Learn more at Stormpath.com
![Page 28: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/28.jpg)
POST
NOT Idempotent
Learn more at Stormpath.com
![Page 29: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/29.jpg)
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
![Page 30: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/30.jpg)
Design Time!
Learn more at Stormpath.com
![Page 31: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/31.jpg)
Base URL
Learn more at Stormpath.com
![Page 32: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/32.jpg)
http(s)://foo.io
vs
http://www.foo.com/dev/service/api/rest
Learn more at Stormpath.com
![Page 33: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/33.jpg)
http(s)://foo.io
Rest Client
vs
Browser
Learn more at Stormpath.com
![Page 34: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/34.jpg)
Versioning
Learn more at Stormpath.com
![Page 35: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/35.jpg)
URL
https://api.stormpath.com/v1
vs.
Media-Type
application/foo+json;application&v=2
application/foo2+json;application
Learn more at Stormpath.com
![Page 36: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/36.jpg)
Resource Format
Learn more at Stormpath.com
![Page 37: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/37.jpg)
Media Type
Content-Type: application/json
When time allows:
application/foo+json
application/foo2+json;bar=baz
…
Learn more at Stormpath.com
![Page 38: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/38.jpg)
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
![Page 39: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/39.jpg)
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
![Page 40: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/40.jpg)
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
![Page 41: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/41.jpg)
createdAt / updatedAt
Learn more at Stormpath.com
![Page 42: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/42.jpg)
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
![Page 43: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/43.jpg)
Response Body
Learn more at Stormpath.com
![Page 44: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/44.jpg)
GET obvious
What about POST?
Return the representation in the response when feasible.
Add override (?_body=false) for control
Learn more at Stormpath.com
![Page 45: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/45.jpg)
Content Negotiation
Learn more at Stormpath.com
![Page 46: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/46.jpg)
Header
• Accept header
• Header values comma delimited in order
of preference
GET /applications/a1b2c3
Accept: application/json, text/plain
Learn more at Stormpath.com
![Page 47: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/47.jpg)
Resource Extension
/applications/a1b2c3.json
/applications/a1b2c3.csv
…
Conventionally overrides Accept header
Learn more at Stormpath.com
![Page 48: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/48.jpg)
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
![Page 49: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/49.jpg)
Links in JSON
• Tricky in JSON
• XML has it (XLink), JSON doesn’t
• How do we do it?
Learn more at Stormpath.com
![Page 50: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/50.jpg)
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
![Page 51: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/51.jpg)
Resource References
aka ‘Linking’
Learn more at Stormpath.com
![Page 52: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/52.jpg)
Instance Reference
GET /accounts/x7y8z9
200 OK
{
“meta”: {“href”:“...”, ...}
“givenName”: “Tony”,
“surname”: “Stark”,
...,
“directory”: ????
}
Learn more at Stormpath.com
![Page 53: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/53.jpg)
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
![Page 54: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/54.jpg)
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
![Page 55: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/55.jpg)
Reference Expansion
(aka Entity Expansion, Link Expansion)
Learn more at Stormpath.com
![Page 56: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/56.jpg)
Account and its Directory?
Learn more at Stormpath.com
![Page 57: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/57.jpg)
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
![Page 58: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/58.jpg)
Partial Representations
Learn more at Stormpath.com
![Page 59: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/59.jpg)
GET
/accounts/x7y8z9?fields=givenName,surname,
directory(name)
Learn more at Stormpath.com
![Page 60: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/60.jpg)
Collections!
Learn more at Stormpath.com
![Page 61: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/61.jpg)
Collections
• A first class resource ‘citizen’
• Own href / metadata
• Own properties
• Different from all other collections
Learn more at Stormpath.com
![Page 62: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/62.jpg)
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
![Page 63: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/63.jpg)
Pagination
Learn more at Stormpath.com
![Page 64: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/64.jpg)
Collection Resource supports query params:
• Offset
• Limit
…/applications?offset=50&limit=25
Learn more at Stormpath.com
![Page 65: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/65.jpg)
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
![Page 66: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/66.jpg)
Sorting
Learn more at Stormpath.com
![Page 67: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/67.jpg)
GET .../accounts?
orderBy=surname,givenName%20desc
Learn more at Stormpath.com
![Page 68: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/68.jpg)
Search
Learn more at Stormpath.com
![Page 69: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/69.jpg)
“Find all accounts with a
‘company.com’ email address
that can login to a particular
application”
Learn more at Stormpath.com
![Page 70: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/70.jpg)
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
![Page 71: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/71.jpg)
Search cont’d
• Filter search
.../accounts?q=some+value
• Attribute Search
.../accounts?surname=Joe&email=*company.c
om
Learn more at Stormpath.com
![Page 72: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/72.jpg)
Search cont’d
• Starts with
?email=joe*
• Ends with
?email=*company.com
• Contains
?email=*foo*
Learn more at Stormpath.com
![Page 73: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/73.jpg)
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
![Page 74: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/74.jpg)
Many To Many
Learn more at Stormpath.com
![Page 75: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/75.jpg)
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
![Page 76: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/76.jpg)
GET /groupMemberships/23lk3j2j3
200 OK
{
“meta”:{“href”: “.../groupMemberships/23lk3j2j3”},
“account”: {
“meta”:{“href”: “...”}
},
“group”: {
“meta”{“href”: “...”}
},
…
}
Learn more at Stormpath.com
![Page 77: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/77.jpg)
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
![Page 78: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/78.jpg)
Async or Long-Lived Operations
Learn more at Stormpath.com
![Page 79: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/79.jpg)
POST /emails
{
“from”: [email protected],
“subject”: “Hi!”
“body”: “...”
}
Learn more at Stormpath.com
![Page 80: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/80.jpg)
204 Accepted
Location: /emails/23Sd932sSl
{
“status”: “queued”,
...
}
Learn more at Stormpath.com
![Page 81: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/81.jpg)
GET /emails/23Sd932sSl
Expires: 2014-09-29T18:00:00.000Z
{
“status”: “sent”,
...
}
Learn more at Stormpath.com
![Page 82: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/82.jpg)
Batch Operations
Learn more at Stormpath.com
![Page 83: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/83.jpg)
• 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
![Page 84: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/84.jpg)
Batch Delete
“Delete all company.com accounts”
DELETE /accounts?
email=*@company.com
Learn more at Stormpath.com
![Page 85: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/85.jpg)
Batch Create / Update
Already have a Collection concept. Use it.
Learn more at Stormpath.com
![Page 86: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/86.jpg)
Batch Create or Update
POST /accounts
{“items”: [
{ ... account 1 ... },
{ ... account 2 ... },
...
]
}
Learn more at Stormpath.com
![Page 87: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/87.jpg)
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
![Page 88: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/88.jpg)
Errors
Learn more at Stormpath.com
![Page 89: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/89.jpg)
• As descriptive as possible
• As much information as possible
• Developers are your customers
Learn more at Stormpath.com
![Page 90: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/90.jpg)
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”
}
Learn more at Stormpath.com
![Page 91: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/91.jpg)
Security
Learn more at Stormpath.com
![Page 92: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/92.jpg)
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
![Page 93: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/93.jpg)
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
![Page 94: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/94.jpg)
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
![Page 95: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/95.jpg)
API Keys
• Entropy
• Password Reset
• Independence
• Scope
• Speed
• Limited Exposure
• Traceability
Learn more at Stormpath.com
![Page 96: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/96.jpg)
IDs
Learn more at Stormpath.com
![Page 97: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/97.jpg)
• IDs should be opaque
• Should be globally unique
• Avoid sequential numbers (contention,
fusking)
• Good candidates: UUIDs, ‘Url64’
Learn more at Stormpath.com
![Page 98: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/98.jpg)
HTTP Method Overrides
Learn more at Stormpath.com
![Page 99: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/99.jpg)
POST /accounts/x7y8z9?_method=DELETE
Learn more at Stormpath.com
![Page 100: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/100.jpg)
Caching &
Concurrency Control
Learn more at Stormpath.com
![Page 101: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/101.jpg)
Server (initial response): ETag: "686897696a7c876b7e”
Client (later request):If-None-Match: "686897696a7c876b7e”
Server (later response):304 Not Modified
Learn more at Stormpath.com
![Page 102: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/102.jpg)
Maintenance
Learn more at Stormpath.com
![Page 103: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/103.jpg)
Use HTTP Redirects
Create abstraction layer / endpoints when
migrating
Use well defined custom Media Types
Learn more at Stormpath.com
![Page 104: Elegant Rest Design Webinar](https://reader033.vdocument.in/reader033/viewer/2022052509/55a8690c1a28ab5a028b4650/html5/thumbnails/104.jpg)
• User Management & Authentication
• API Security & Access Management
• Eliminate months of development
• Automatic security best practices
Coming Soon!
Loopback support