Designing REST services with Spring MVC

Serhii KartashovDecember 2015SoftjournInternship

Agenda

What is REST?

CRUD operations

Status codes

Media types

SpringMVC instruments

Agenda

What is REST?

CRUD operations

Status codes

Media types

SpringMVC instruments

What is REST?

• REpresentational State Transfer

• Client/Server, Stateless, Uniform Interface

• Hightly-Cohesive, loosely coupled services

Uniform Interface

• Identification of resources

• Manipulation of resources

• Self-describing of resources

Representations of the resource over a network

• URI - Uniform Resource Identifier• URL - Uniform Resource Locator• URN - Uniform Resource Name

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 resourcePOST, GET, PUT, DELETE, ...

• Headers describes the messagesContent-Type: application/json

GET

• Retrieve Information• Must be save and idempotent• Get can be conditional or partial

If-Modified-SinceRange

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

PUT

• Requests that the entity passed, be stored at the URI

• Can be used to modify an existing onePUT /accounts/0/creditcards/1

POST

• Requests that the resource at the URI do something with the enclosed entityCreate, ModifyPOST /accounts

Agenda

What is REST?

CRUD operations

Status codes

Media types

SpringMVC instruments

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

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: /accountsResponse: [{"id":0,"name":"Mike"}, {...}, {...}]

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"}

Create new credit card

• That just a request for creation credit card automatically

POST: /accounts/2/creditcardsjson: {"pin":1111, "cardNumber":2, "cardStatus":"ACTIVE", "remnant":0.0}

List the current credit cards of account

• Need to return to us a collection of all available credit cards

GET: /accounts/2/creditcardsResponse: [ {"pin":1111, "cardNumber":2, "cardStatus":"ACTIVE", "remnant":0.0} ]

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

Lock Credit Card

• Changed status of credit card

PUT: /accounts/2/creditcards/2{"pin":1111, "cardNumber":2, "cardStatus":"LOCKED", "remnant":20.0}

Delete account

• No input required• No output required

DELETE /accounts/2

Agenda

What is REST?

CRUD operations

Status codes

Media types

SpringMVC instruments

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

Success Status Codes• 200 OKEverything worked• 201 CreatedThe server has successfully created a new resourceNewly created resource’s location returned in the Location header• 202 AcceptedThe server has accepted the request, but it is not yet completeA location to determine the request’s current status can be returned in the Location header

Client Error Status Codes

• 400 Bad RequestMalformed syntaxShould not be repeated without modification• 401 UnauthorizedAuthentication is requiredIncludes a WWW- Authenticate header‐• 403 ForbiddenServer has understood but refuses to honor the requestShould not be repeated without modification

Client Error Status Codes

• 404 Not FoundThe server cannot find a resource matching a URI• 406 Not AcceptableThe server can only return response entities that do not match the client’s Accept header• 409 ConflictThe resource is in a state that is in conflict with the requestClient should attempt to rectify the conflict and then resubmit the request

Agenda

What is REST?

CRUD operations

Status codes

Media types

SpringMVC instruments

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

Common Media Types

• Application– JSON: application/json– XML: application/xml– PDF: application/pdf

• Text– HTML: text/html– PLAIN: text/plain

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

Agenda

What is REST?

CRUD operations

Status codes

Media types

SpringMVC instruments

What other instruments Spring MVC can provide?

• @RestControllerUnion of @Controller and @RequestBody

annotations• @RequestBody• @RequestMapping

value; method; consumes; produces• @PathVariable• @RequestParam

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

What more?

• Testing REST with MockMvc• REST Client• Caching• Version handling• Scaling: CDN (Content Delivery Network)

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