COMP9321
Data Services Engineering
Term 1, 2021
Week 5 REST Services Part 2
2
Architectural Constraints of REST
1. Client-Server
2. Uniform Interface
3. Statelessness
4. Caching
5. Layered System
6. Code on demand (optional)
If your design satisfies the first five, you can say your API is ‘RESTful’
On Uniform Interface – Linked Resources
Representations are hypermedia: resource (data itself) + links to other resources
e.g., Google Search representation:
3
On Uniform Interface – Linked Resources
All three services expose the same functionality, but their usability increases towards the right
• Service A is a typical remote-function style service, exposing everything through a single URI. Neither addressable, nor connected
• Service B is addressable but not connected; there are no indication of the relationships between resources. A hybrid style …
• Service C is addressable and well-connected; resources are lined to each other in ways that make sense. A fully RESTful service
4
5
On Uniform Interface – Linked Resources
Example: Pagination
6
Statelessness
REST API must be stateless
All calls from clients are independent
1. Client-Server
2. UniformInterface 3. Statelessness 4. Caching
5. LayeredSystem
Stateless means every HTTP request happens in a complete isolation.
Stateless is good !! – scalable, easy to cache, addressable URI can be bookmarked (e.g., 10th page of search results)
HTTP is by nature stateless. We do something to break it in order to build applications
the most common way to break it is ’HTTP sessions’
the first time a user visits your site, he gets a unique string that identifies his session with the site
http://www.example.com/forum?PHPSESSIONID=27314962133
the string is a key into a data structure on the server which contains what the user has been up to. All interactions assume the key to be available to manipulate the data on the server
On Statelessness
What counts as ‘state’ exactly?
Think a Flickr.com-like web site … you will add photos, rename photos, share them with friends, etc. – what would ‘being stateless’ mean here?
KEY notion: separation of client application state and RESTful resource state.
• consider the application state as data that could vary by client, and per request.
• consider the resource state as data that could is centrally managed by the server. It is the same for every client.
• resource states live on the server
• individual client application states should be kept off the server
Consider a scenario: a little photo edit app + Flickr and other APIs … 7
On Statelessness
Statelessness in REST applies to the client application state (from the server’s view point)
What does this mean to the client application?
• every REST request should be totally self-descriptive
• client transmit the state to the server for every request that needs it.
HTTP Request (URL and the parameters)
HTTP Request Headers (e.g., accept)
Body Content
a RESTful service requires that the application state to stay on the client side. Server does not keep the application state on behalf of a client
What about OAuth? Is it conflicting with the Statelessness of REST? 8
Caching
Responses must be marked ‘cachable’ or ‘non-cachable’
1. Client-Server
2. UniformInterface 3. Statelessness
4. Caching
5. LayeredSystem
Well-managed caching partially or completely eliminates some client–server interactions, improving scalability and performance.
Being Stateless: every action happens in isolation: – Keepstheinteractionprotocolsimpler
– Buttheinteractionsmaybecome‘chattier’
To scale, RESTful API must be work-shy (only generate data traffic when needed, other times use cache)
This requires ’server-client’ collaboration:
• Client provide guard clauses in requests so that servers can determine easily if there’s any work to be done
• If-Modified-Since, Last Modified, If-None-Match/ETag 9
10
https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/http-caching?hl=en
Caching (Defining optimal Cache-Control policy)
11
Caching
Caching
Server needs cache management policy and implementation … 12
1. Client-Server LayeredSystem 2. UniformInterface
3. Statelessness
4. Caching
5. LayeredSystem
13
A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way.
Again, de-coupling allows the components in the architecture to evolve independently
The Richardson Maturity Model
Leonard Richardson: can we measure to what level your service is RESTful?
Level 0: One URI (single endpoint) exposed, requests contain operation details
Level 1: Expose resource URIs – individual URIs for each resource. Requests could still contain some operation details
Level 2: HTTP Methods – use the standard HTTP methods, status codes with the resource URIs,
Level 3: HATEOAS – self-documenting responses, responses include links that the client can use
14
A good read: https://martinfowler.com/articles/richardsonMaturityModel.html
Interacting with RESTful API (workflow)
What would it be like to have a stateless conversation with API vs. stateful conversation with API? (e.g., POST -> return ID, forget vs. POST-> return no ID, plant Cookies)
Take the Coffee Order Process from Jim Webber as example … The customer workflow:
15
customers advance towards the goal of drinking some coffee by interacting with the Starbucks service, the customer orders, pays, and waits for the drink, between ‘order’ and ‘pay’, the customer can update (asking for skimmed milk)
Interacting with RESTful API (workflow)
The barista workflow:
16
the barista loops around looking for the next order to be made, preparing the drink, and taking the payment,
The outputs of the workflow are available to the customer when the barista finishes the order and releases the drink
Points to Remember: We will see how each transition in two state machines is implemented as an interaction with a Web resource. Each transition is the combination of a HTTP verb on a resource via its URI causing state changes.
Customer’s View Point
Place an order: POST-ing on http://api.starbucks.com/orders
POST /orders HTTP/1.1
Host: xxx
Content-Type: application/xml
Coffee Order
Client
Starbucks API
201 Created
Location: …/order?1234 Content-Type: application/xml
17
Oops … A mistake!
I like my coffee to be strong
Need another shot of espresso, what are my OPTIONS?
OPTIONS /order?1234 HTTP/1.1 Host: xxx
Client
Coffee Order
200 OK
Allow: GET, PUT
Starbucks API
18
I can still update my order
Update the order
PUT /order?1234 HTTP/1.1 Host: xxx
Content-Type: application/xml
Client
Coffee Order (shot)
200 OK
Location: …/order?1234 Content-Type: application/xml
Starbucks API
19
Possible conflict with another workflow
The resource state can change without you … (before your PUT-ing getting to the server)
PUT /order?1234 HTTP/1.1 Host: xxx
Content-Type: application/xml
Other Client
Coffee Order (made)
20
Client
Starbucks API
409 Conflict
Location: …/order?1234
Possible conflict with another workflow
What are my OPTIONS now? How do I recover?
OPTIONS /order?1234 HTTP/1.1 Host: xxx
Client
Coffee Order (made)
21
200 OK Allow: GET
Starbucks API
OK, update successful, what now?
Idea floated here is … FOLLOW THE LINK.
GET /order?1234 HTTP/1.1 Host: xxx
Accept: application/xml
Client
Coffee Order (shot)
Starbucks API
200 OK
Location: …/order?1234 Content-Type: application/xml
A related resource
22
Pay for the order
PUT /payment/order?1234 HTTP/1.1 Host: xxx
Content-Type: application/xml
Client
Starbucks API
Coffee Order (shot)
Payment
201 Created
Location: …payment/order?1234 Content-Type: application/xml
Check that you have paid?
GET /payment/order?1234 HTTP/1.1 Host: xxx
Coffee Order (shot)
Payment
Client
Starbucks API
200 OK
Location: … /payment/order?1234 Content-Type: application/xml
25
Changing the API conversation?
26
Tools of the Trade
• Python
• Pandas
• Flask RESTX • Swagger
27
Flask and Flask RESTX
• Flask is a Python Micro Web Framework. It allows you to build light- weight Web Apps, but it has good capabilities because it support extensions (there are many)
• Flask RESTX is an extension for Flask that adds support for quickly building REST APIs. Flask-RESTX encourages best practices with minimal setup. It provides a coherent collection of decorators and tools to describe your API and expose its documentation properly (using Swagger). Flask RESTX is a forked project of Flask RESTplus. So far they are 100% compatible.
Swagger
• When using Flask RESTPlus, A Swagger API documentation is automatically generated and available on your API root but you need to provide some details with the Api.doc() decorator
• Swagger (now the “Open API Initiative) is a framework for describing your API using a common language that everyone can understand. Think of it as a blueprint for a house. You can use whatever building materials you like, but you can’t step outside the parameters of the blueprint.
• Let’s have a look (http://editor.swagger.io)
28
29
Questions