This is introduction presentation for interns

1. Designing REST services with
Spring MVC
Serhii Kartashov
December 2015
Softjourn
Internship

2. Agenda
What is REST?
CRUD operations
Status codes
Media types
SpringMVC instruments

3. Agenda
What is REST?
CRUD operations
Status codes
Media types
SpringMVC instruments

4. What is REST?
• REpresentational State Transfer
• Client/Server, Stateless, Uniform Interface
• Hightly-Cohesive, loosely coupled services

5. Uniform Interface
• Identification of resources
• Manipulation of resources
• Self-describing of resources

6. Representations of the resource over a
network
• URI - Uniform Resource Identifier
• URL - Uniform Resource Locator
• URN - Uniform Resource Name

7. HTTP's uniform interface
• URI's identify resources
/accounts/0
• HTTP verbs descried a limited set of
operations that can be used to manipulate a
resource
POST, GET, PUT, DELETE, ...
• Headers describes the messages
Content-Type: application/json

8. GET
• Retrieve Information
• Must be save and idempotent
• Get can be conditional or partial
If-Modified-Since
Range

9. DELETE
• Requests that a resource be removed
• The resource doesn't have to be removed
immediately
• Removal may be a long running task
DELETE /accounts/0

10. PUT
• Requests that the entity passed, be stored at
the URI
• Can be used to modify an existing one
PUT /accounts/0/creditcards/1

11. POST
• Requests that the resource at the URI do
something with the enclosed entity
Create, Modify
POST /accounts

12. Agenda
What is REST?
CRUD operations
Status codes
Media types
SpringMVC instruments

13. Interaction Model
• List the current accounts in bank
• Create new account
• Create new credit card
• List the current credit cards of account
• Make transaction between two credit cards
• Lock credit card
• Delete account

14. List the current accounts in bank
• Need to return to us a collection that
represents
• Design doesn't have Account1, Account2,
Account..., just accounts
GET: /accounts
Response: [{"id":0,"name":"Mike"}, {...}, {...}]

15. Create new account
• Need to create new account in bank with
providing name of person
• Good practice is returning already created
account
POST: /accounts
json: {"name":"Matt"}
Response: {"id":2,"name":"Matt"}

16. Create new credit card
• That just a request for creation credit card
automatically
POST: /accounts/2/creditcards
json: {"pin":1111, "cardNumber":2,
"cardStatus":"ACTIVE", "remnant":0.0}

17. List the current credit cards of account
• Need to return to us a collection of all
available credit cards
GET: /accounts/2/creditcards
Response: [ {"pin":1111, "cardNumber":2,
"cardStatus":"ACTIVE", "remnant":0.0} ]

18. Make transaction between two credit
cards
• Transaction be running during some time
• Possible situation when you created just a
request for transaction and receive just info
when this will be precessed
POST: /accounts/2/creditcards
json: {"fromCreditCard": "1", "toCreditCard": "2",
"amount": "20"}
Transaction successfully processed

19. Lock Credit Card
• Changed status of credit card
PUT: /accounts/2/creditcards/2
{"pin":1111, "cardNumber":2,
"cardStatus":"LOCKED", "remnant":20.0}

20. Delete account
• No input required
• No output required
DELETE /accounts/2

22. Agenda
What is REST?
CRUD operations
Status codes
Media types
SpringMVC instruments

23. Status codes
• Status codes indicates the results of the
server's attempt to satisfy the request
• Broadly divided into categories
– 1XX: Informational
– 2XX: Success
– 3XX: Redirection
– 4XX: Client Error
– 5XX: Server Error

24. Success Status Codes
• 200 OK
Everything worked
• 201 Created
The server has successfully created a new resource
Newly created resource’s location returned in the
Location header
• 202 Accepted
The server has accepted the request, but it is not yet
complete
A location to determine the request’s current status can
be returned in the Location header

25. Client Error Status Codes
• 400 Bad Request
Malformed syntax
Should not be repeated without modification
• 401 Unauthorized
Authentication is required
Includes a WWW-‐Authenticate header
• 403 Forbidden
Server has understood but refuses to honor the
request
Should not be repeated without modification

26. Client Error Status Codes
• 404 Not Found
The server cannot find a resource matching a URI
• 406 Not Acceptable
The server can only return response entities that do
not match the client’s Accept header
• 409 Conflict
The resource is in a state that is in conflict with the
request
Client should attempt to rectify the conflict and
then resubmit the request

28. Agenda
What is REST?
CRUD operations
Status codes
Media types
SpringMVC instruments

29. Communication between client and
server
Content types are negotiated using headers:
• Client describes what it wants with the Accept
header
• Server (and client during POST and PUT)
describes what it is sending with Content-
Type header

30. Common Media Types
• Application
– JSON: application/json
– XML: application/xml
– PDF: application/pdf
• Text
– HTML: text/html
– PLAIN: text/plain

31. Addition Media Types
• Image
– JPEG: image/jpeg
• Audio
– MP4: audio/mp4
– WEBM: audio/webm
• Video
– MP4: video/mp4
– WEBM: video/webm
• Prefix vnd (vendor specific files)
– application/vnd.android.package-archive - for apk files
– application/vnd.ms-excel

32. Agenda
What is REST?
CRUD operations
Status codes
Media types
SpringMVC instruments

33. What other instruments Spring MVC
can provide?
• @RestController
Union of @Controller and @RequestBody
annotations
• @RequestBody
• @RequestMapping
value; method; consumes; produces
• @PathVariable
• @RequestParam

34. What other instruments Spring MVC
can provide?
• @RequestHeader
• @MatrixVariable
/owners/{ownerId}/pets/{petId}
GET /owners/42;q=11;r=12/pets/21;q=22;s=23
@MatrixVariable(pathVar="petId") Map<String, String>
petMatrixVars
<mvc:annotation-driven enable-matrix-
variables="true"/>
• @SessionAttributes
• @ModelAttribute
• @CookieValue

35. What more?
• Testing REST with MockMvc
• REST Client
• Caching
• Version handling
• Scaling: CDN (Content Delivery Network)

36. Useful links
• Tutorials
– http://www.restapitutorial.com/
• Video & Articles
– https://www.youtube.com/watch?v=5WXYw4J4QOU
– ETags: http://www.infoq.com/articles/etags
– Manage REST API versions:
http://stackoverflow.com/questions/20198275/how-to-manage-rest-api-
versioning-with-spring?answertab=votes#tab-
tophttp://stackoverflow.com/questions/20198275/how-to-manage-rest-api-
versioning-with-spring?answertab=votes#tab-top
– Steps towards the glory of REST:
http://martinfowler.com/articles/richardsonMaturityModel.html
• Examples from presentation: https://github.com/searhiy/REST-examples
• Instruments & Tools
– https://github.com/spring-projects/spring-data-rest
– http://spring.io/blog/2009/03/27/rest-in-spring-3-resttemplate