This document provides an introduction and overview of web services and RESTful APIs. It discusses the benefits of separating an application into logical layers and exposing business logic through services. It defines web services, microservices, and REST principles. It explains how RESTful resources are addressed with URIs and represented with formats like JSON. It outlines the HTTP methods GET, POST, PUT, PATCH, and DELETE and how they map to create, retrieve, update, and delete operations. It also covers SOAP and challenges it addresses compared to REST. Finally, it discusses HTTP status codes for indicating success and error responses.

1. Introduction to Web Services
Jeff Anderson
janderson141@cscc.edu
Center for Workforce Development

2. Why Services?
• Promotes separation of duties between the
each layer in the architecture
• Allows the presentation layer to focus on
user interaction
• Centralizes business rules and business logic
in the application service layer
• Delegates data persistence to the data
access layer

3. Web Services
• Extend the service layer onto the network so it can
be used by any number of clients all around the
world
• Client applications become much lighter weight and
focus on user interactions, not business logic and
persistence
• Multiple versions of an application, such as web,
iOS, Android, Alexa, ”Hey Google”, etc. share
business rules making them faster and less
expensive to develop
• Allows other applications to collaborate with ours
• Promotes loose coupling and use of domain specific
languages in each layer by exchanging data in a text
format such as JavaScript Object Notation (JSON)

4. Microservices
“In short, the microservice architectural style is an approach to
developing a single application as a suite of small services, each
running in its own process and communicating with lightweight
mechanisms, often an HTTP resource API. These services are built
around business capabilities and independently deployable by fully
automated deployment machinery. There is a bare minimum of
centralized management of these services, which may be written in
different programming languages and use different data storage
technologies.”
-- James Lewis and Martin Fowler
https://martinfowler.com/microservices/

5. Simple Object Access Protocol
(SOAP)
Types of Webservices

6. Simple Object Access Protocol (SOAP)
• A W3C recommendation for exchanging structured information in a
decentralized, distributed environment
• Uses eXtensible Markup Language (XML) to exchange data in ways
documented using Web Services Description Language (WSDL)
• Defines an extensible framework providing a message construct that
can be exchanged over a variety of underlying protocols
• Designed to be independent of any particular programming model or
language
https://www.w3.org/TR/soap12-part1/#intro

7. Example SOAP Request
https://www.w3schools.com/XML/xml_soap.asp

8. Example SOAP Response
https://www.w3schools.com/XML/xml_soap.asp

9. Challenges With SOAP Services
• XML parsing is complex and can be slow to process
• The Extensible Stylesheet Language (XSL) and XML Path Language
(XPath) assist with transforming XML but add another level of
complexity
• The WSDL can be used to generate code for working with SOAP web
services but versioning becomes a problem when the WSDL needs to
change
• While SOAP may be simpler than it’s predecessors, it is way more
complex than it’s name would imply
• In most organizations, SOAP web services are consider ”legacy” code

10. REpresentational State Transfer
(REST)
Types of Webservices

11. Representational State Transfer (REST)
• A network based architectural style for proposed by Roy Thomas
Fielding in his PhD Dissertation at the University of California in 2000
• A stateless, cacheable, client-server based architectural style for
building distributed applications at internet scale
• Uses HTTP as the application-level protocol for communication and
transfer of resource representations
• Resources can be represented any number of ways, such as XML or
JSON, and are negotiated via “accept” and “content-type” headers
• Actions to be performed are articulated through HTTP methods with
success or failure denoted by HTTP status codes
https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

12. Principles of REST
• Resources expose easily understood directory structure URIs.
• Representations transfer JSON or XML to represent data objects and
attributes.
• Messages use HTTP methods explicitly (for example, GET, POST, PUT,
and DELETE).
• Stateless interactions store no client context on the server between
requests. State dependencies limit and restrict scalability. The client
holds session state.
https://spring.io/understanding/rest#principles-of-rest

13. Resources
REST Webservices

14. REST Resources
“The key abstraction of information in REST is a resource. Any
information that can be named can be a resource: a document or
image, a temporal service (e.g. "today's weather in Los Angeles"), a
collection of other resources, a non-virtual object (e.g. a person), and so
on. In other words, any concept that might be the target of an
author's hypertext reference must fit within the definition of a
resource. A resource is a conceptual mapping to a set of entities, not
the entity that corresponds to the mapping at any particular point in
time.”
– Roy Fielding
https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2_1_1

15. Uniform Resource Identifier (URI)
• http://www.ietf.org/rfc/rfc2396.txt
• tel:+1-816-555-1212
• mailto:John.Doe@example.com
• ftp://ftp.is.co.za/rfc/rfc1808.txt
• ldap://[2001:db8::7]/c=GB?objectClass?one
• urn:oasis:names:specification:docbook:dtd:xml:4.1.2
https://tools.ietf.org/html/rfc3986#section-1.1.2

16. REST Resource Representations
Use nouns to describe entity sets:
• The collection of customers:
/customers
• A single customer:
/customers/{customerId}
• Accounts of a particular customer:
/customers/{customerId}/accounts
https://www.thoughtworks.com/insights/blog/rest-api-design-resource-modeling

17. Challenges / Guidance
• Balance the grain so applications are not too chatty
• Resource naming should not depend on the API consumer knowing
control flow of business processes
• Clients should not be able to leave the system in an inconsistent state
• Consider naming resources after business processes that encapsulate
intent and operate in a consistent way on dependent collections
such as /accounts/{accountId}/transactions or
/customers/{customerId}/changeOfAddress
• Business process resource names should still be nouns to the extent
possible
https://www.thoughtworks.com/insights/blog/rest-api-design-resource-modeling

18. HTTP Methods
Invoking REST Services

19. Safe Methods
• Safe means GET and HEAD methods should only retrieve data with no
significant side effects
• This enables other methods, such as POST, PUT and DELETE to be
special in a way the user would expect that a possibly unsafe action is
being requested
https://tools.ietf.org/html/rfc2616#section-9.1.1

20. Idempotent Methods
• Idempotent means, aside from error or expiration issues, the side-
effects of N > 0 (multiple) identical requests is the same as for N = 1 (a
single) request
• GET, HEAD, PUT and DELETE are idempotent
• OPTIONS and TRACE SHOULD NOT have side effects, and so are
inherently idempotent
https://tools.ietf.org/html/rfc2616#section-9.1.2

21. GET
Retrieve whatever information (in the form of an entity) identified by
the Request-URI. Example: Retrieve an address with an ID of 1:
GET /addresses/1
• GET can be conditional if the request includes an If-Modified-Since,
If-Unmodified-Since, If-Match, If-None-Match, or If-Range header
field
• GET can be partial if the request includes a Range header field or
request parameters for limiting results
• Responses are cacheable to reduce latency and network traffic
• Using request headers, the client can request uncached data
https://tools.ietf.org/html/rfc7231#section-4.3.1

22. POST
Requests the origin server accept the entity enclosed in the request as
a new subordinate of the resource identified by the Request-URI in the
Request-Line. Example: Create a new address:
POST /addresses
• The posted entity is subordinate to that URI in the same way that a
file is subordinate to a directory containing it or a record is
subordinate to a database
• Often POST is used to create a new entity, but it can also be used to
update an entity
https://tools.ietf.org/html/rfc7231#section-4.3.3

23. PUT
Requests the enclosed entity be stored under the supplied Request-URI. Example:
create or modify the address with an ID of 1:
PUT /addresses/1
• If the Request-URI refers to an already existing resource, the enclosed entity
SHOULD be considered as a modified version of the one residing on the origin
server
• If the Request-URI does not point to an existing resource, and that URI is capable
of being defined as a new resource by the requesting user agent, the origin server
can create the resource with that URI
• A PUT request is idempotent which is the main difference between the
expectations of PUT versus a POST request
• PUT replaces an existing entity. If only a subset of data elements are provided,
the rest will be replaced with empty or null
https://tools.ietf.org/html/rfc7231#section-4.3.4

24. PATCH
Requests that a set of changes described in the request entity be
applied to the resource identified by the Request-URI
• The set of changes is represented in a format called a "patch
document" identified by a media type
• If the Request-URI does not point to an existing resource, the server
MAY create a new resource
• Collisions from multiple PATCH requests may be more dangerous than
PUT collisions because some patch formats need to operate from a
known base-point or else they will corrupt the resource
• The PATCH method affects the resource identified by the Request-URI,
and it also MAY have side effects on other resources
• PATCH is neither safe nor idempotent
https://tools.ietf.org/html/rfc5789

25. DELETE
Remove an entity at a URI.
Example: remove the address with an ID of 1:
DELETE /addresses/1
• The delete may be logical in that previous versions continue to exist
https://tools.ietf.org/html/rfc7231#section-4.3.5

26. HTTP Status Codes
Invoking REST Services

27. 2xx – Success
• 200 OK – the request succeeded (GET, PUT, PATCH)
• 201 Created – a new resource has been created (PUT, POST)
• 202 Accepted – the request has been accepted for processing which
has not yet completed
• 204 No Content – the request was successful and there is no content
to be returned (DELETE)
https://tools.ietf.org/html/rfc7231#section-6.3

28. 4xx – Client Error
• 400 Bad Request – the request had malformed syntax and was not
understood
• 401 Unauthorized – the request requires valid client authentication
and authorization
• 403 Forbidden – the request is understood but is being rejected for
any of a variety of reasons
• 404 Not Found – the URI references a non existent resource
• 405 Method Not Allowed – the client made a request using an HTTP
Method that is not supported by the server
• 415 Unsupported Media Type – the request is not in a supported
format
https://tools.ietf.org/html/rfc7231#section-6.5

29. 500 – Server Error
• 500 Internal Server Error – an unexpected error prevented the
request from being fulfilled
• 503 Service Unavailable – The server is down or overloaded and
unable to handle the request
https://tools.ietf.org/html/rfc7231#section-6.6

30. Cross-Origin Resource Sharing
(CORS)
Using REST Services

31. Typical Modern Web Application
https://www.w3.org/TR/cors/

32. The Problem
http://d111111abcdef8.cloudfront.net

33. Hypermedia As The Engine Of
Application State (HATEOAS)
Designing REST Services

34. Hypermedia as the Engine of Application State
• Is a constraint applied to the REST application architecture
• The goal of HATEOAS is to isolate application state in the server rather
than the client
• A hypermedia-driven site provides information to navigate the site's
REST interfaces dynamically by including hypermedia links with the
responses
• These hypermedia links represent valid state transitions, any of which
the client can choose next
• Whereas SOAP uses tightly coupled WSDL-driven interfaces which are
defined at compile time, HATEOAS uses loosely coupled dynamically
generated interfaces defined at run time
https://spring.io/understanding/HATEOAS

35. HATEOAS Example
https://spring.io/understanding/HATEOAS

36. Where To Go For More
Webservices

37. Further Reading
• Understanding REST from the Spring website
• REST API Design – Resource Modeling by Prakash Subramaniam
• Understanding HATEOAS from the Spring website
• Richardson Maturity Model by Martin Fowler
• GitHub API Documentation
• Architectural Styles and the Design of Network-based Software
Architectures by Roy Fielding
• RFC 7231, Hypertext Transfer Protocol
• Cross-Origin Resource Sharing by W3C