1 © Donald F. Ferguson, 2015. All rights reserved.Modern Internet Service Oriented Application Development – Lecture 2: REST Details and Patterns Some

1 © Donald F. Ferguson, 2015. All rights reserved.

Modern Internet Service Oriented Application Development –Lecture 2: REST Details and Patterns

SomeDetails



Asynchronous Operations

• Assembling applications from micro-services is “cool”

• But, getting a response to a GET or PUT might take a while– The action implementation requires talking to other micro-services,

which in turn talk to other micro-services.– You need to assume that calls are occurring over a network.– Some operations take a little while, e.g. a complex DB query.– Some micro-services are inherently asynchronous, e.g. because they are people

– PUT …/account/21 with some data has an implementation– That sends and email to Bob who has to make sure the account data is OK– And sends an “approved” or “not approved” email response– Before the original PUT can return success or failure

• Holding the “connection” while a long task is running is icky– Consumes resources and may block other calls due to limits on active requests– Network are unreliable, and connections break. This can result in really icky

– My PUT failed. I will try again.– Failed again. I will try again.– … …



Asynchronous Operation



Implementation Observations

• Define a collection /QueuedResponses– A client can call …/QueuedResponses/21 to get a specific response.

– You already know how to do this for …/staff, …/stores

– The data format in the table is {id, status, JSONString}, where JSONString is the response you would have

received for a synchronous request.

• A simple implementation would be writing a façade – Accept request

– Create new table entry with status = “in progress”

– Return 202 and URL

– Call the actual implementation

– Update the database table entry with the JSON result

• Most application platforms have middleware approaches to support registering callbacks, threads, etc.

The implementation would typically– Invoke some long running action, e.g. DB query, workflow process and register a callback

– The callback implementation updates the entry in the response table.



Example Considerations• Service Endpoint

– Endpoint– Endpoint Encryption

• Requests and Authentication– Request Headers– Request Timestamps– Request Authentication– Response Headers

• Resources– Resource Requests– Resource Representation– Resource Methods– Synchronous Operations– Asynchronous Operations– Success Response Codes– Failure Response Codes

• Resource Data Types– Atomic Types– Complex Type - Object or Structure– Resource Relationships– Resource References

• Pagination– Through HTTP Link Header– Syntax and Example of Pagination Link Header– Consistency Across Page Requests

• Versioning– Version Header– Version URI

• Saying “REST is not enough• You have to define a set of patterns/

conventions of URLs, headers, …



Headers – Some Choices I MadeHTTP Request Header Value Mandatory

auth-timestamp: The current POSIX time. Yes

auth-key: The user or client’s uniqueAPI KEY.

Yes

auth-signature: The HMAC-SHA256 digest for the request.

Yes

api-version: (Optional) API version string

No

Accept: (Optional) application/xml or application/json

No

Nonce: One time UUID to enableidempotency/duplicate detection



Response CodesOperation HTTP Request HTTP Response Codes Supported

READ GET 200 - OK with message body204 - OK no message body 206 - OK with partial message body

CREATE POST 201 - Resource created (Operation Complete)202 - Resource accepted (Operation Pending)

UPDATE PUT 202 - Accepted (Operation Pending)204 - Success (Operation Complete)

DELETE DELETE 202 - Accepted (Operation Pending)204 - Success (Operation Complete)

Examples of Link Headers in HTTP response:

Link: <http://api/jobs/j1>;rel=monitor;title="update profile"Link: <http://api/reports/r1>;rel=summary;title=”access report”

202 means

• Your request went asynch.

• The HTTP header Linkis where to poll for rsp.



Failure Response CodeError Response Code

Invalid Parameter 400 - Invalid parameter

Authentication 401 - Authentication failure

Permission Denied 403 - Permission denied

Not Found 404 - Resource not found

Invalid Request Method 405 - Invalid request method

Internal Server Error 500 - Internal Server Error

Service Unavailable 503 - Service Unavailable



Assignment 1



Setup• Form teams

– If you have already formed your team,

– Give your team a “name.”

– Elect a leader. If you cannot elect a leader using Rock-Paper-Lizard-Scissors-Spock,

or something similar.

– The leader sends me an email of the form

“Our team is the Bobcats

Bobcats, dff9, Ferguson, Donald, [email protected]

Bobcats, js2001, Smith, John, [email protected]

Bobcats, gw1031, Washington, George, [email protected]”

– If you have not formed your teams,

– Why not?

– I think maybe 2 people sent emails saying they do not have a team.

– I will form teams randomly at the break.

• Perform the following computation

– Form a set that is all of the team members UNIs without the text prefix.

– Choose the smallest number in the set, which we will call x

– Compute N = x MOD 3

– If

– N = 0, your team’s datamodel is Customer Data

– N = 1, your team’s datamodel is Movie Information

– N = 2, your team’s datamodel is Business

– N = 3, you do not know what MOD means

mailto:[email protected]





The Project• Setup

– You may pick any language, runtime, framework, DB, … you want.– You will create a database “schema” for you model and populate with sample data– You do not need to rigorously adhere to “table” and “column” names

• Implement a REST service for your information model with– A resource representation for each “type” in the model, e.g. store, staff– GET, PUT, POST and DELETE operations for each “type”– Navigable relationships, e.g. …/store/manager– All PUT operations must implement an asynchronous response, e.g.

Receive request, response accepted with link to rsp, sleep(x),update the response– Implement a template based query language, e.g.

– …/humans?q=“iq=50&hairColor=red” with only “=“ operators– That returns the collection elements with fields equal to the input

– Pagination– Projection:

– GET …/humans?fields=“iq,shoeSize” returns– PUT contains a JSON object with the fields to update



Grading• The grade for the project is based on

– Top-Level Design Spec– Demo– Code review

• Top-Level Design Spec structure– Introduction– Uniform Resource Representation:

– How your API surfaces each of the concepts– A couple of examples

– Implementation technology you used– Implementation

– How you implemented each of the concepts– A couple of examples

– Issues

• Due dates– Your design document is due 06-February– We will do code reviews and demos via eMeetings the week of 09-February

• Do not panic!

• I will help you if you are confused/unsure.

• Just do the best you can. I will providefeedback on the first version.

• Do not panic!

Documents

1 © Donald F. Ferguson, 2015. All rights reserved.Modern Internet Service Oriented Application Development – Lecture 2: REST Details and Patterns Some