REST API Design for JAX-RS And Jersey

Views:
 
     
 

Presentation Description

Designing and building a really clean and intuitive ReST API is no small feat. You have to worry about resources, collections of resources, pagination, query parameters, references to other resources, which HTTP methods to use, HTTP caching, security, and more. And you have to make sure it lasts and doesn’t break clients as you add features over time. Furthermore, although there are many references on creating REST APIs with XML, there are far fewer references on REST + JSON. It is enough to drive you crazy. This session demonstrates how to design and implement an elegant REST API. Sign up for Stormpath: https://api.stormpath.com/register More from Stormpath: http://www.stormpath.com/blog

Comments

Presentation Transcript

slide 1:

REST + JSON APIs with JAX-RS Les Hazlewood CTO Stormpath stormpath.com

slide 2:

.com • Identity Management and Access Control API • Security for your applications • User security workflows • Security best practices • Developer tools SDKs libraries

slide 3:

Outline • 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 • Coding Time JAX-RS-based App

slide 4:

Why REST • Scalability • Generality • Independence • Latency Caching • Security • Encapsulation Learn more at Stormpath.com

slide 5:

HATEOAS • Hypermedia • As • The • Engine • Of • Application • State Further restriction on REST architectures. Learn more at Stormpath.com

slide 6:

REST Is Easy Learn more at Stormpath.com

slide 7:

REST Is Hard for providers Learn more at Stormpath.com

slide 8:

REST can be easy if you follow some guidelines Learn more at Stormpath.com

slide 9:

Example Domain: Stormpath • Applications • Directories • Accounts • Groups • Associations • Workflows

slide 10:

Fundamentals Learn more at Stormpath.com

slide 11:

Resources Nouns not Verbs Coarse Grained not Fine Grained Architectural style for use-case scalability Learn more at Stormpath.com

slide 12:

/getAccount /createDirectory /updateGroup /verifyAccountEmailAddress What If Learn more at Stormpath.com

slide 13:

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

slide 14:

Keep It Simple Learn more at Stormpath.com

slide 15:

The Answer Fundamentally two types of resources: Collection Resource Instance Resource Learn more at Stormpath.com

slide 16:

Collection Resource /applications Learn more at Stormpath.com

slide 17:

Instance Resource /applications/a1b2c3 Learn more at Stormpath.com

slide 18:

Behavior • GET • PUT • POST • DELETE • HEAD Learn more at Stormpath.com

slide 19:

Behavior POST GET PUT DELETE ≠ 1:1 Create Read Update Delete Learn more at Stormpath.com

slide 20:

Behavior As you would expect: GET Read DELETE Delete HEAD Headers no Body Learn more at Stormpath.com

slide 21:

Behavior Not so obvious: PUTand POSTcan bothbe used for Create andUpdate Learn more at Stormpath.com

slide 22:

PUT for Create Identifier is known by the client: PUT /applications/clientSpecifiedId … Learn more at Stormpath.com

slide 23:

PUT for Update Full Replacement PUT /applications/existingId “name”: “Best App Ever” “description”: “Awesomeness” Learn more at Stormpath.com

slide 24:

PUT Idempotent Learn more at Stormpath.com

slide 25:

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

slide 26:

POST as Update On instance resource POST /applications/a1b2c3 “name”: “Best App Ever. Srsly.” Response: 200 OK Learn more at Stormpath.com

slide 27:

POST NOT Idempotent Learn more at Stormpath.com

slide 28:

Media Types • Format Specification + Parsing Rules • Request: Accept header • Response: Content-Type header • application/json • application/foo+json • application/foo+jsonapplication • … Learn more at Stormpath.com

slide 29:

Design Time Learn more at Stormpath.com

slide 30:

Base URL Learn more at Stormpath.com

slide 31:

https://api.foo.com vs http://www.foo.com/dev/service/api/r est Learn more at Stormpath.com

slide 32:

https://api.foo.com Rest Client vs Browser Learn more at Stormpath.com

slide 33:

Versioning Learn more at Stormpath.com

slide 34:

URL https://api.stormpath.com/v1 vs. Media-Type application/json+fooapplicationv1 Learn more at Stormpath.com

slide 35:

Resource Format Learn more at Stormpath.com

slide 36:

Media Type Content-Type: application/json When time allows: application/foo+json application/foo+jsonbarbazv1 … Learn more at Stormpath.com

slide 37:

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

slide 38:

Date/Time/Timestamp There’s already a standard. Use it: ISO 8601 Example: … “createdTimestamp”: “2012-07-10T18:02:24.343Z” Use UTC Learn more at Stormpath.com

slide 39:

HREF • Distributed Hypermedia is paramount • Every accessible Resource has a unique URL. • Replaces IDs IDs exist but are opaque. “href”: https://api.stormpath.com/v1/accounts/x7y8z9” … Critical for linking as we’ll soon see Learn more at Stormpath.com

slide 40:

Response Body Learn more at Stormpath.com

slide 41:

GET obvious What about POST Return the representation in the response when feasible. Add override _bodyfalse for control Learn more at Stormpath.com

slide 42:

Content Negotiation Learn more at Stormpath.com

slide 43:

Header • Accept header • Header values comma delimited in order of preference GET /applications/a1b2c3 Accept: application/json text/plain Learn more at Stormpath.com

slide 44:

Resource Extension /applications/a1b2c3.json /applications/a1b2c3.csv … Conventionally overrides Accept header Learn more at Stormpath.com

slide 45:

Resource References aka ‘Linking’ Learn more at Stormpath.com

slide 46:

• Hypermedia is paramount. • Linking is fundamental to scalability. • Tricky in JSON • XML has it XLink JSON doesn’t • How do we do it Learn more at Stormpath.com

slide 47:

Instance Reference GET /accounts/x7y8z9 200 OK “href”: “https://api.stormpath.com/v1/accounts/x7y8z9” “givenName”: “Tony” “surname”: “Stark” … “directory”: Learn more at Stormpath.com

slide 48:

Instance Reference GET /accounts/x7y8z9 200 OK “href”: “https://api.stormpath.com/v1/accounts/x7y8z9” “givenName”: “Tony” “surname”: “Stark” … “directory”: “href”: “https://api.stormpath.com/v1/directories/g4h5i6” Learn more at Stormpath.com

slide 49:

Collection Reference GET /accounts/x7y8z9 200 OK “href”: “https://api.stormpath.com/v1/accounts/x7y8z9” “givenName”: “Tony” “surname”: “Stark” … “groups”: “href”: “https://api.stormpath.com/v1/accounts/x7y8z9/groups” Learn more at Stormpath.com

slide 50:

Reference Expansion aka Entity Expansion Link Expansion Learn more at Stormpath.com

slide 51:

Account and its Directory Learn more at Stormpath.com

slide 52:

GET /accounts/x7y8z9expanddirectory 200 OK “href”: “https://api.stormpath.com/v1/accounts/x7y8z9” “givenName”: “Tony” “surname”: “Stark” … “directory”: “href”: “https://api.stormpath.com/v1/directories/g4h5i6” “name”: “Avengers” “creationDate”: “2012-07-01T14:22:18.029Z” … Learn more at Stormpath.com

slide 53:

Partial Representations Learn more at Stormpath.com

slide 54:

GET /accounts/x7y8z9fieldsgivenNamesurname directoryname Learn more at Stormpath.com

slide 55:

Pagination Learn more at Stormpath.com

slide 56:

Collection Resource supports query params: • Offset • Limit …/applicationsoffset50limit25 Learn more at Stormpath.com

slide 57:

GET /accounts/x7y8z9/groups 200 OK “href”: “…/accounts/x7y8z9/groups” “offset”: 0 “limit”: 25 “first”: “href”: “…/accounts/x7y8z9/groupsoffset0” “previous”: null “next”: “href”: “…/accounts/x7y8z9/groupsoffset25” “last”: “href”: “…” “items”: “href”: “…” “href”: “…” … Learn more at Stormpath.com

slide 58:

Many To Many Learn more at Stormpath.com

slide 59:

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

slide 60:

GET /groupMemberships/23lk3j2j3 200 OK “href”: “…/groupMemberships/23lk3j2j3” “account”: “href”: “…” “group”: “href”: “…” … Learn more at Stormpath.com

slide 61:

GET /accounts/x7y8z9 200 OK “href”: “…/accounts/x7y8z9” “givenName”: “Tony” “surname”: “Stark” … “groups”: “href”: “…/accounts/x7y8z9/groups” “groupMemberships”: “href”: “…/groupMembershipsaccountIdx7y8z9” Learn more at Stormpath.com

slide 62:

Errors Learn more at Stormpath.com

slide 63:

• As descriptive as possible • As much information as possible • Developers are your customers Learn more at Stormpath.com

slide 64:

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

slide 65:

Security Learn more at Stormpath.com

slide 66:

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

slide 67:

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

slide 68:

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

slide 69:

API Keys • Entropy • Password Reset • Independence • Speed • Limited Exposure • Traceability Learn more at Stormpath.com

slide 70:

IDs Learn more at Stormpath.com

slide 71:

• IDs should be opaque • Should be globally unique • Avoid sequential numbers contention fusking • Good candidates: UUIDs ‘Url64’ Learn more at Stormpath.com

slide 72:

HTTP Method Overrides Learn more at Stormpath.com

slide 73:

POST /accounts/x7y8z9_methodDELETE Learn more at Stormpath.com

slide 74:

Caching Concurrency Control Learn more at Stormpath.com

slide 75:

Server initial response: ETag: "686897696a7c876b7e” Client later request: If-None-Match: "686897696a7c876b7e” Server later response: 304 Not Modified Learn more at Stormpath.com

slide 76:

Maintenance Learn more at Stormpath.com

slide 77:

Use HTTP Redirects Create abstraction layer / endpoints when migrating Use well defined custom Media Types Learn more at Stormpath.com

slide 78:

IT’S CODING TIME • Let’s build a JAX-RS REST App • git clone https://github.com/stormpath/todos- jersey.git Learn more at Stormpath.com

slide 79:

.com • Free for any application • Eliminate months of development • Automatic security best practices Sign Up Now: Stormpath.com Les Hazlewood | lhazlewood

authorStream Live Help