Web services

Krishantha Dinesh Msc, MIEEE, MBCS

Software Architect.
www.krishantha.com
www.youtube.com/krish
Road Map

• Web services

• Microservices

• Service scaling

• Security

• Continues integration

• API Management

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

Agenda

• Little bit about others

• More about RESTful

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

WARNING

If(mobilephone){

throw new LeaveTheSessionException(“sorry”);

//No mobile phones != silent mode

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

• Webservice that follows the SOA employs a loose coupling between the entities.

• So client is not coupled to a server, but to a service. Thus, the integration of the server to use takes place outside of
the scope of the client application programs.

• control of business processes can be isolated. A business rule engine can be incorporated to control the workflow of
a defined business process. Depending on the state of the workflow, the engine calls the respective services.

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

SOA Concept

Discovery (service
description)

find publish

interact
Service requester
Service provider
(client)

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

Technologies

• Xml

• The markup language that underlies most of the specifications used for Web services. XML separated from its
presentation to a specific device.

• SOAP

• SOAP is a protocol but similar to JDBC, is a network, transport, and programming language and platform neutral
protocol that allows a client to call a remote service. The message format is XML.

• WSDL

• WSDL is an XML-based interface and implementation description language. The service provider uses a WSDL
document in order to specify the operations a Web service provides, as well as the parameters and data types of
these operations. A WSDL document also contains the service access information.
* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/
SOAP

• SOAP is a lightweight protocol intended for exchanging structured information in a decentralized, distributed
environment. SOAP uses XML technologies to define an extensible messaging framework, which provides a message
construct that can be exchanged over a variety of underlying protocols. The framework has been designed to be
independent of any particular programming model and other implementation specific semantics.

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

• This protocol consists of three parts:

• An envelope that defines a framework for describing message content and processing instructions.

• A set of encoding rules for expressing instances of application-defined data types.

• A convention for representing remote procedure calls and responses.

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

 REST
Representational State Transfer
• It is an architectural pattern for developing web services as opposed to a specification

• It is architectural style for distributed hypermedia systems

• first presented by Roy Fielding in 2000 for his PhD dissertation.

(https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

6 pillars

REST does have it’s own 6 guiding constraints which must be satisfied if an interface needs to be referred as RESTful.

• Uniform interface

• Client–server

• Stateless

• Cacheable

• Layered system

• Code on demand (optional)

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

01. Uniform interface

Once a developer becomes familiar with one of your API, he should be able to follow the similar approach for other APIs.)

• you MUST decide APIs interface for resources inside the system which are exposed to API consumers and follow
religiously. A resource in the system should have only one logical URI and that should provide a way to fetch related
or additional data.

• Any single resource should not be too large and contain each and everything in its representation. Whenever
relevant, a resource should contain links (HATEOAS) pointing to relative URIs to fetch related information.

• All resources should be accessible through a common approach such as HTTP GET and similarly modified using a
consistent approach.

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

02. Client - server

Servers and clients may evolve and developed independently, as long as the interface between them is not altered.

• This essentially means that client application and server application MUST be able to evolve separately without any
dependency on each other. A client should know only resource URIs and that’s all. Today, this is normal practice in
web development so nothing fancy is required from your side. Keep it simple.

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

03. Stateless

No client context shall be stored on the server between requests. The client is responsible for managing the state of the
application.

• Roy fielding got inspiration from HTTP, so it reflects in this constraint. Make all client-server interaction stateless.
Server will not store anything about latest HTTP request client made. It will treat each and every request as new. No
session, no history.

• If client application needs to be a stateful application for the end user, where user logs in once and do other
authorized operations thereafter, then each request from the client should contain all the information necessary to
service the request – including authentication and authorization details.

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

04. Cacheable

• In today’s world, caching of data and responses is of utmost important wherever they are applicable/possible.
Caching brings performance improvement for client side, and better scope for scalability for a server because the load
has reduced.

• In REST, caching shall be applied to resources when applicable and then these resources MUST declare themselves
cacheable. Caching can be implemented on the server or client side.

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

05. Layered system

• REST allows you to use a layered system architecture where you deploy the APIs on server A, and store data on server
B and authenticate requests in Server C, for example. A client cannot ordinarily tell whether it is connected directly to
the end server, or to an intermediary along the way.

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

06. Code on demand

• This constraint is optional. Most of the time you will be sending the static representations of resources in form of XML
or JSON. But when you need to, you are free to return executable code to support a part of your application e.g.
clients may call your API to get a UI widget rendering code. It is permitted. (be aware about security)

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

REST Resource Naming Guide

• 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 in his dissertation

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

• In REST, primary data representation is called Resource.

• A resource can be a singleton or a collection. For example, “students” is a collection resource and “student” is a
singleton resource. We can identify “students” collection resource using the URI “/students”. We can identify a single
“student” resource using the URI “/student/{studentId}”.

• A resource may contain sub-collection resources also. For example, sub-collection resource “course” of a particular
“student” can be identified using the URN “/students/{studentId}/courses”.

• Similarly, a singleton resource “course” inside the sub-collection resource “courses” can be identified as follows:
“/students/{studentId}/courses/{courseId}”.

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

REST Resource Naming Best Practices

1. Use nouns to represent resources

Eg: if we have to manage below resources in COSMOS system

• Users of the system

• User Accounts

• Vehicles

http://api.codelabs.lk/cosmos/vehicle-management/vehicles

http://api.codelabs.lk/cosmos/vehicle-management/vehicles/{vehicle-id}

http://api.codelabs.lk/cosmos/user-management/users

http://api.codelabs.lk/cosmos/user-management/users/{id}

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

Resource archetypes has 4 categories.

1. Document

2. Collection

3. Store

4. controller

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

Document
• A document resource is a singular concept that is align to an object instance or database record. In REST, you can
view it as a single resource inside resource collection. A document’s state representation typically includes both fields
with values and links to other related resources.

• Use “singular” name to denote document resource archetype.

• http://api.codelabs.lk/cosmos/user-management/users/{id}

• http://api.codelabs.lk/cosmos/user-management/users/admin

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

Collection
• A collection resource is a server-managed directory of resources. Clients may propose new resources to be added to a
collection. However, it is up to the collection to choose to create a new resource, or not. A collection resource
chooses what it wants to contain and also decides the URIs of each contained resource.

• Use “plural” name to denote collection resource archetype.

• http://api.codelabs.lk/cosmos/user-management/users

• http://api.codelabs.lk/cosmos/user-management/users/{id}/projects

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

Store
• A store is a client-managed resource repository. A store resource lets an API client put resources in, get them back
out, and decide when to delete them. A store never generates new URIs. Instead, each stored resource has a URI that
was chosen by a client when it was initially put into the store.

• Use “plural” name to denote store resource archetype.

• http://api.codelabs.lk/cosmos/user-management/users/{id}/wishlists

• http://api.codelabs.lk/cosmos/user-management/users/{id}/wishlists/homeneeds

• http://api.codelabs.lk/cosmos/user-management/users/{id}/wishlists/birthdayparty

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

Controller
• A controller resource models a procedural concept. Controller resources are like executable functions, with
parameters and return values; inputs and outputs.

• Use “verb” to denote controller archetype.

• http://api.codelabs.lk/cosmos/cart-management/users/{id}/cart/checkout

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

Consistency

• Use consistent resource naming conventions and URI formatting for minimum ambiguity and maximum readability
and maintainability.

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

/
• Use forward slash (/) to indicate a hierarchical relationships

http://api.codelabs.lk/cosmos/user-management/users

http://api.codelabs.lk/cosmos/user-management/users/{id}

• Do not use trailing forward slash (/) in URIs

http://api.codelabs.lk/cosmos/user-management/users/ X

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

• Use hyphens (-) to improve the readability of URIs

http://api.codelabs.lk/cosmos/usermanagement/users

http://api.codelabs.lk/cosmos/user-management/users

• Do not use underscores ( _ )

its possible to use an underscore in place of a hyphen to be used as separator. But depending on the application’s font,
it’s possible that the underscore character can either get partially obscured or completely hidden in some browsers or
UIs.

http://api.codelabs.lk/cosmos/user_management/users

http://api.codelabs.lk/cosmos/user-management/users

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

• Use lowercase letters in URIs

All possible cases, lowercase letters should be consistently preferred in URI paths.

RFC 3986 defines URIs as case-sensitive except for the scheme and host components.
(https://tools.ietf.org/html/rfc3986)

http://api.codelabs.lk/cosmos/user-management/users/{id}/wishlists/birthdaylist //A

http://API.CODELABS.LK/cosmos/user-management/users/{id}/wishlists/birthdaylist //B

http://api.codelabs.lk/cosmos/user-management/users/{id}/wishlists/BirthdayList //C

A and B treat as same but C is not

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

• Do not use file extensions

http://api.codelabs.lk/cosmos/reports/sales.html

http://api.codelabs.lk/cosmos/reports/sales

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

Never use CRUD function names in URIs
• URIs should not be used to indicate that a CRUD function is performed. URIs should be used to uniquely identify
resources and not any action upon them. HTTP request methods should be used to indicate which CRUD function is
performed.

HTTP GET http://api.codelabs.lk/cosmos/user-management/users //Get all users

HTTP GET http://api.codelabs.lk/cosmos/user-management/users/{userId} //Get user for given Id

HTTP POST http://api.codelabs.lk/cosmos/user-management/users //Create new user

HTTP POST http://api.codelabs.lk/cosmos/user-management/createUser

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

• Use query component to filter URI collection but not to identify. If key is to identify resource use path parameter
and to filter use query parameter.

Many times, you will come across requirements where you will need a collection of resources sorted, filtered or limited
based on some certain resource attribute. For this, do not create new APIs – rather enable sorting, filtering and
pagination capabilities in resource collection API and pass the input parameters as query parameters

HTTP GET http://api.codelabs.lk/cosmos/user-management/users/{userId}

HTTP GET http://api.codelabs.lk/cosmos/user-management/users?status=active

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

Status Codes

• 100 series information – (its fine)

• 200 success (you are Good)

• 300 redirection (go away)

• 400 client side errors (you messed up)

• 500 server side errors (I messed up)

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

Is Rest services as Async?

• Yes if use messaging. Other wise if we use rest over synchronous protocol we cannot get real sync behavior

* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/

 Q&A
* http://www.krishantha.com * https://www.youtube.com/krish * https://www.linkedin.com/in/krish-din/