REST and RESTful Services

1. Representational State
Transfer
TECH9810 - System Architectures

2. What is REST?
● Representational State Transfer (REST) is a way of
abstracting and exposing service state and behaviour
● The big idea in REST is that service state and behaviour
are modeled as resources

3. What is REST?
● The consumer interacts with one or more service
resources using message passing API having a well-
defined URI scheme over HTTP
● Service resources themselves can be backed by concrete
state, such as a database table, or be synthetic in nature
such as modelling behaviour of some service function
(e.g. a service element is running or not)

4. State Representation
● REST says nothing about the representation of state in
the request and response messages
● Importantly, resource representation in REST is
independent of actual internal service representation

5. State Representation
● In practice, REST implementations use popular
serialisation technologies such as JSON and XML for
encoding state in messages

6. What’s it like?
● Let’s imagine I have a website, where I sell stuff, and I
need to update the site by adding new items onto the site,
updating prices and descriptions, or removing items once
they are sold.

7. What’s it like?

8. What’s it like?
REST
API

9. What’s it like?
Request
REST
API

10. What’s it like?
Request
Response
REST
API

11. What’s it like?
● If I want to update the website, I need to give the server an instruction
via REST, the instruction usually takes the form of a URI, which looks
a lot like a web address, so if I wanted to modify on of the Items my
site, this could be the instruction, or the more commonly used term is
ENDPOINT.
http://shop.damiantgordon.com/API/SaleItems

12. What’s it like?
● If I want to update the website, I need to give the server an instruction
via REST, the instruction usually takes the form of a URI, which looks
a lot like a web address, so if I wanted to modify on of the Items my
site, this could be the instruction, or the more commonly used term is
ENDPOINT.
http://shop.damiantgordon.com/API/SaleItems
Scheme Authority Path
(or Resource)

13. What’s it like?
Request
● So what type of Requests might we want to do?
REST
API

14. What’s it like?
● So what type of Requests might we want to do?

15. What’s it like?
● In REST we call these using HTTP operations:

16. What’s it like?
● In REST we call these using HTTP operations:
● CREATE HTTP POST
● READ HTTP GET
● UPDATE HTTP PUT
● DELETE HTTP DELETE

17. What’s it like?
● So what do Requests and Responses look like?
Request
Response
REST
API

18. What’s it like?
● So what do Requests and Responses look like?
Request Response

19. What’s it like?
● So what do Requests and Responses look like?
HEADER
OPERATION
ENDPOINT
PARAMETERS/BODY
Request Response

20. What’s it like?
● So what do Requests and Responses look like?
http://shop.damiantgordo
n.com/API/SaleItems
OPERATION
HEADER
Request Response
PARAMETERS/BODY

21. What’s it like?
● So what do Requests and Responses look like?
POST/GET/
PUT/DELETE
HEADER
Request Response
http://shop.damiantgordo
n.com/API/SaleItems
PARAMETERS/BODY

22. What’s it like?
● So what do Requests and Responses look like?
POST/GET/
PUT/DELETE
Request Response
http://shop.damiantgordo
n.com/API/SaleItems
Authentication Data
PARAMETERS/BODY

23. What’s it like?
● So what do Requests and Responses look like?
POST/GET/
PUT/DELETE
Request Response
http://shop.damiantgordo
n.com/API/SaleItems
Authentication Data
New Price

24. What’s it like?
● So what do Requests and Responses look like?
Request Response

25. What’s it like?
● So what do Requests and Responses look like?
Request Response

26. Other HTTP Operations
● As well as POST, GET, PUT, and DELETE, there are two
more HTTP operations worth mentioning:
● HTTP PATCH – Works the same as PUT but
can be used to partially update the contents of
a resource
● HTTP OPTIONS - Used to query characteristic
of the associated resource

27. PUT versus PATCH
PUT:
PATCH:
curl -X PUT https://api.example.com/customers/237324632/notices/213 -d
{
"subject": "Account status",
"body": "Dear john, please review your outstanding balance ...",
"delivery": "normal"
}
curl -X PATCH https://api.example.com/customers/237324632/notices/213 -d
{
"delivery": "normal"
}

28. Uniform Resource Identifier (URI)
● The URI is defined by an IETF standard which describes its overall form and
what characters are legally permitted to be used
● A URI is made up from a URL (locator) and a URN (a unique name)
● The general form is as follows:
● Where:
○ Scheme is the transfer protocol (e.g. http or https)
○ Authority is the service address (e.g. api.example.com)
○ Path is the fully-qualified resource name including the URN (e.g. /users/1234)
○ Query is an optional set of qualifying parameters (e.g. limit=100)
{scheme}://{authority}{path}?{query}

29. Example URI
● The following URI from the github API illustrates how URIs are formed
● Here, the URI scheme is secured HTTP and the authority is api.github.com
● The path is /users which is the resource name (i.e. the users collection)
● The query parameter since specifies the user ID to start from, qualifying the
API call
● A resource identifier is effectively globally unique though this says nothing
about whether the resource itself is unique
https://api.github.com/users?since=1000

30. Resource Design
● In REST, a resource is just an independent representation
of some service state or behaviour
● But it can be challenging to create a REST API that
effectively models the service while also optimally serving
the requirements of its consumers

31. Resource Design
● The problem is that the REST API designer has to try to
anticipate how the API will be used and in what way
● Ideally the API development would take place with an
active consumer helping to inform the design
requirements throughout
● But this is not always possible and even when it is, it’s
often no better than a snapshot in time

32. Architectural Constraints
● Client-Server: Establishes the separation of concerns
between the service provider and the service consumer.
The provider offers one or more capabilities and listens for
requests for those capabilities. The consumer is
responsible for presenting the responses to the user and
taking any corrective actions on foot of errors

33. Architectural Constraints
● Stateless: The principle that no server-side state exists
between any two REST requests from a consumer, i.e.
requests are self-contained and standalone. Contrast this
with a transactional style, for example

34. Architectural Constraints
● Cacheable: Service responses can be explicitly labeled
as cacheable or non-cacheable. This allows
intermediating caching nodes to reuse previous
responses to requests without having to go all the way
back to the service. This is a key idea in making RESTful
services scalable

35. Architectural Constraints
● Layered: An arbitrary number of nodes can be placed
between the ultimate service and service consumer. Their
existence must be fully transparent so that they can be
added and removed at will. This allows for the distribution
and scalability of RESTful service solutions in practice

36. Architectural Constraints
● Uniform Contract: This constraint states that all services
and service consumers must share a single, overall
technical interface. This is the primary constraint that
really distinguishes REST from other architectures. In
REST, this is applied using the verbs (commands) and
media types of HTTP. The contract is usually free from
specific business logic context so that it can be consumed
by as wide a variety of client types as possible.

37. REST in Operation

38. Items and Collections
● Resources fall broadly into two basic types
• An item resource is a single resource used to represent
some concrete or synthetic group of attributes, usually
represented as key/value pairs (e.g. an invoice record in a
database or monitored performance attributes of a server)
• A collection resource is a group of item resources of the
same item resource type

39. Items and Collections
● Items and collections has slightly different semantics in a
RESTful API so they support some but not all of the same
messages as we will see
● Both types are uniquely identified by a URI

40. Idempotence
● Idempotence is the property of an operation such
that the operation can be applied multiple times to
some value without changing the outcome
beyond its first application

41. Idempotence
● In the context of REST, we can say that some
operations are idempotent if, after the first
application of an operation on a resource (which
may alter service state), subsequent applications
of that operation don’t alter the service state, no
matter how many times that operation is later
applied

42. Idempotence
● Consideration of idempotence is important in the
context of a message passing API over a latent,
unreliable network as clients need guaranteed
API semantics in the face of potential network
partitions

43. The Good, the Bad, and
the Interesting of
REST

44. THE GOOD

45. REST: Benefits
● Supports all types of data formats
● In other types of APIs, you are limited in your
choice of data formats. However, RESTful APIs
support all data formats.
45

46. REST: Benefits
● Works wonders with web browsers
● In RESTful APIs, you can send an HTTP
request, get JavaScript Object Notation (JSON)
data in response, and parse that data to use it
on the client applications. This makes it the
best choice for web browsers. Furthermore,
you can easily integrate these APIs with your
existing website.
46

47. REST: Benefits
● Uses less bandwidth
● Thanks to JSON, RESTful APIs use less
bandwidth as compared to other types of APIs.
However, this stands true for JSON-based web
APIs only. An XML-based web API will have a
similar payload to its non-RESTful counterpart
whether it adheres to the REST architectural
constraints or not.
47

48. REST: Benefits
● Does not need to be designed from scratch
● In most cases, you can get models that you can
modify and use. For example, NetApp and
Mailgun provide a complete tutorial and source
code for building a private API
48

49. REST: Benefits
● Easy for most developers
● RESTful APIs use HTTP methods for
communication. You can use Python,
JavaScript (Node.js), Ruby, C#, and a number
of other languages to develop these APIs,
making them easier to work with for most
developers.
49

50. THE BAD

51. REST: Weaknesses
● Lack of a Standard
● Because REST APIs can be built any which
way, as a developer, you have to learn about
each one from scratch. If the documentation or
support is poor, this can be very difficult, if not
impossible.
51

52. REST: Weaknesses
● Lack of State
● Most web applications require stateful mechanisms.
If you purchase a website which has a mechanism
to have a shopping cart. It is required to know the
number of items in the shopping cart before the
actual purchase is made. This burden of
maintaining the state lies on the client, which makes
the client application heavy and difficult to maintain.
52

53. REST: Weaknesses
● Learning About New REST APIs
● Every REST API is different, even though many
seem similar. WordPress, Drupal, and Joomla
are three different content management
systems that have the concept of a blog post
and a REST API to interact with posts, but they
each have different Routes and accept different
variables for various Request Types.
53

54. THE INTERESTING

55. REST: Interesting
● It supports JSON and XML
● There are developers for all tastes and an API
should aim to adapt to them all. Thus, another
advantage of REST API is that it satisfies the
expectations of those who use the JSON
language as much as it satisfies those that rely
on XML.
55

56. REST: Interesting
● It is more simple than SOAP
● Beyond the REST architecture, developers are
using the standard SOAP, another possibility
when writing an API. The main advantage of
the former over the latter is that its
implementation is much simpler.
56

57. REST: Interesting
● Documentation
● Each change in the architecture of the REST
API should be reflected in its documentation so
that any developer using it knows what to
expect.
57

58. REST: Interesting
● Error messages
● When making a mistake while working with an
API, any developer will appreciate knowing
what the error has been. Hence, the possibility
offered by the REST architecture of including
error messages providing some clue in this
regard is also relevant.
58