Lecture 08 Web Services
Lecture 08 Web Services
Lecture 08 Web Services
Learning Outcomes
After completing this session you should be able to explain
Web services
REST Concepts
JSON
Web Services
Web services are software programs that interact with other software
programs
Web Services
Web services provide a standard means of interoperating between
different software applications, running on a variety of platforms and/or
frameworks
Web Services
There are two popular approaches to web services: SOAP (Simple Object
Access Protocol) and REST (REpresentational State Transfer)
Other approaches such as gRPC and GraphQL are also available which tries to
alleviate the limitations of SOAP and REST services
Web Services: SOAP
SOAP is an XML-based protocol for making network API requests
WSDL enables code generation so that a client can access a remote service
using local classes and method calls (which are encoded to XML messages and
decoded again by the framework)
Stateless Uniform
Interface
Web Services: REST
Constraints Induced Properties
● Client-Server ● Performance
● Layered System ● Scalability
● Stateless ● Simplicity
● Cache ● Modifiability
● Visibility
● Code on Demand (Optional) ● Portability
● Uniform Interface ● Reliability
○ Identification of Resources
○ Resource Representation
○ Self Descriptive Messages
○ HATEOAS
Web Services: REST
When used over HTTP , a URL is used to identify a resource and HTTP
methods are used as verbs to manipulate them
a document or image,
Example:
HATEOAS allow clients to deal with discovering the resources and the
identifiers
Links
Example:
GET /hotels/xyz
HTTP provides four basic methods for the four most common operations
HTTP GET
HTTP PUT
HTTP POST
HTTP DELETE
Operations: GET
The HTTP GET method is used to retrieve (or read) a representation of a
resource
In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD
REQUEST)
GET http://www.example.com/customers/12345
GET http://www.example.com/customers/12345/orders
GET http://www.example.com/buckets/sample
Operations: PUT
PUT is most-often utilized for update capabilities, PUT-ing to a
known/existing resource URI with the request body containing the newly-
updated representation of the original resource
However, PUT can also be used to create a resource in the case where the
resource ID is chosen by the client instead of by the server
On successful update, return 200 (or 204 if not returning any content in the
body) from a PUT
Operations: PUT
If using PUT for create, return HTTP status 201 on successful creation
It is not necessary to return a link via a Location header in the creation case
since the client already set the resource ID
Operations: PUT
PUT is not a safe operation, in that it modifies (or creates) state on the
server, but it is idempotent
if you create or update a resource using PUT and then make that same call
again, the resource is still there and still has the same state as it did with the
first call
Operations: PUT
Examples:
PUT http://www.example.com/customers/12345
PUT http://www.example.com/customers/12345/orders/98765
PUT http://www.example.com/buckets/secret_stuff
Operations: POST
The POST verb is most-often utilized for creation of new resources
When creating a new resource with POST request to the parent resource, the
service takes care of associating the new resource with the parent and
assigning an ID (new resource URI) to it
Operations: POST
On successful creation, return HTTP status 201, returning a Location
header with a link to the newly created resource
Making two identical POST requests will most-likely result in two resources
containing the same information
Operations: POST
Examples:
POST http://www.example.com/customers
POST http://www.example.com/customers/12345/orders
Operations: DELETE
DELETE is used to remove a resource identified by a URI
DELETE http://www.example.com/customers/12345
DELETE http://www.example.com/customers/12345/orders
DELETE http://www.example.com/buckets/sample
Operations: HEAD
HTTP HEAD: Retrieve a metadata-only representation
A client can use HEAD to check whether a resource exists, or find out other
information about the resource, without fetching its entire representation
HEAD gives you exactly what a GET request would give you, but without the
entity-body
Operations: OPTIONS
HTTP OPTIONS: Check which HTTP methods a particular resource supports
The OPTIONS method lets the client discover what it’s allowed to do to a
resource
The response to an OPTIONS request contains the HTTP Allow header, which
lays out the subset of the operations this resource supports
What status code (message) be returned to the client, when the operation
succeeds or when it fails
GET
PUT
POST
DELETE
Operations Summary
HTTP Verb /customers /customers/{id}
GET 200 (OK), list of customers. Use pagination, 200 (OK), single customer. 404 (Not
sorting and filtering to navigate big lists Found), if ID not found or invalid
PUT 404 (Not Found), unless you want to 200 (OK) or 204 (No Content). 404
update/replace every resource in the entire (Not Found), if ID not found or
collection invalid
POST 201 (Created), 'Location' header with link to 404 (Not Found)
/customers/{id} containing new ID
DELETE 404 (Not Found), unless you want to delete the 200 (OK). 404 (Not Found), if ID
whole collection (not often desirable) not found or invalid
Going beyond the HTTP Operations
How do you activate a customer account?
REST doesn’t allow you to have arbitrary operations on the resources, and
you’re more or less restricted to the list of available HTTP methods, so you
can’t have a request that looks like this:
{ "date": "2015-05-15T13:05:05Z" }
This code will create an activation resource that represents the activation state
of the user
Doing this also gives the added advantage of giving the activation resource
additional properties (date in this example)
Make the action a property of the resource
If activation is a simple state of the customer account, you can simply make
the action a property of the resource, and then use the PATCH HTTP method
to do a partial update to the resource
Example:
{ "active" : "true" }
REST Best Practices
Use HTTP Verbs to Mean Something
Any API consumer is capable of sending GET, POST, PUT, and DELETE
verbs, and they greatly enhance the clarity of what a given request does
Also, GET requests must not change any underlying resource data.
Measurements and tracking may still occur, which updates data, but not
resource data identified by the URI
REST Best Practices
Sensible Resource Names
Use the HTTP methods to specify the verb portion of the request
REST Best Practices
XML and JSON
Favor JSON support as the default, but unless the costs of offering both
JSON and XML are staggering, offer them both
REST Best Practices
Create Fine-Grained Resources
It's much easier to create larger resources later from individual resources
than it is to create fine-grained or individual resources from larger
aggregates
Exercise
Let's say we're describing an order system with customers, orders, line items,
products, etc.
POST http://www.example.com/customers
GET http://www.example.com/customers/33245
The same URI would be used for PUT and DELETE, to update and delete,
respectively
Resource URI Examples
For creating a new Product
POST http://www.example.com/products
GET|PUT|DELETE http://www.example.com/products/66432
POST http://www.example.com/customers/33245/orders
Resource URI Examples
For retrieving an order by its id without having to know the customer
GET http://www.example.com/orders/8769
GET
http://www.example.com/customers/33245/orders/8769/lineitems
/1
Resource URI Examples
For getting list of orders that customer with id 33245 has created or owns
GET http://www.example.com/customers/33245/orders
POST
http://www.example.com/customers/33245/orders/8769/lineitems
Resource URI Examples
There aren't any hard and fast rules, only make sure the imposed structure
makes sense to consumers of your services
More info at
https://www.restapitutorial.com/resources.html
Other Guidelines
https://github.com/microsoft/api-guidelines/blob/vNext/
Guidelines.md
https://cloud.google.com/apis/design/resources#what_is_a_
rest_ap
Other Issues in RESTful API design
Querying, Filtering, and Pagination
Service Versioning
Date/Time Handling
Securing Services
https://www.restapitutorial.com/
JSON (ECMA-404, RFC-8259)
JavaScript Object Notation (JSON) is a lightweight, text-based,
language independent data interchange format
JSON can represent four primitive types (strings, numbers, booleans, and
null) and two structured types (objects and arrays)
The RPC model tries to make a request to a remote network service look
the same as calling a function or method in your programming language,
within the same process (this abstraction is called location transparency)
Other Web Services
Some of the example of recent Web Service related technologies includes
As in many RPC systems, gRPC is based around the idea of defining a service,
specifying the methods that can be called remotely with their parameters
and return types
On the server side, the server implements this interface and runs a gRPC
server to handle client calls
On the client side, the client has a stub that provides the same methods as
the server
gRPC
gRPC and Protocol Buffers
Protocol Buffer is Google’s mature open source mechanism for serializing
structured data
gRPC can also be used with other data formats such as JSON
Service Definition
Four Kinds of Services
Unary RPCs where the client sends a single request to the server and gets a
single response back
Four Kinds of Services
Server streaming RPCs where the client sends a request to the server and
gets a stream to read a sequence of messages back
The client reads from the returned stream until there are no more messages.
Once the client has finished writing the messages, it waits for the server to
read them and return its response
The two streams operate independently, so clients and servers can read and
write in whatever order they like
On the server side, the server implements the methods declared by the
service and runs a gRPC server to handle client calls
The client can then just call those methods on the local object, wrapping the
parameters for the call in the appropriate protocol buffer message type
gRPC looks after sending the request(s) to the server and returning the
server’s protocol buffer response(s)
gRPC and Protocol Buffer References
https://grpc.io/docs/guides/
https://developers.google.com/protocol-buffers/docs/
gotutorial
Advantages of Using gRPC
With gRPC we can define our service once in a .proto file and implement
clients and servers in any of gRPC’s supported languages
The service can be run in environments ranging from servers inside Google to
your own tablet - all the complexity of communication between different
languages and environments is handled for you by gRPC
You also get all the advantages of working with protocol buffers, including
efficient serialization, a simple IDL, and easy interface updating
GraphQL
GraphQL is a query language for your API, and a server-side runtime for
executing queries by using a type system you define for your data
GraphQL isn't tied to any specific database or storage engine and is instead
backed by your existing code and data
GraphQL
A GraphQL service is created by defining types, and fields on those types, then
providing functions for each field on each type
A received query is first checked to ensure it only refers to the types and fields
defined, then runs the provided functions to produce a result.
GraphQL
GraphQL uses the Schema Definition Language (SDL)
Example
GraphQL Queries
Lets, look at how retrieving data works in GraphQL
Below is shown example query for the id part of all hotels in the previous
schema