Elegant Rest Design Webinar

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.

Sign up for Stormpath: https://api.stormpath.com/register
More from Stormpath: https://stormpath.com/blog

Transcript

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