Introduction to Web Services and API's

Web services are a standardized way or a medium to propagate communication between the client and the server applications on the world wide web.

Web Service Architecture

The architecture diagram of the web services shows you how it works, we have a client and the server, the server is hosting the web service in which we want to connect to, as a client over the world wide web means the internet request to the server, and the server responds back to the request, this is called as web services.

client-server-architecture

What is an API:

An API is an acronym for application programming interface and it allows two applications to interact with each other. Each time you use Facebook application and sending an instant message, this will be possible only through API's and Even checking the weather from your phone in your location is also from API.

Difference between Web services and API's :
Web Services API's
Webservices facilitates communication between two machines over Network An API acts as an interface between two different applications so that they can connect each other
All Web services are APIs But all APIs are not Web services
A Webservices use only three types of use: SOAP, REST, and XML-RPC for communication Whereas API may use any style for communication
A Web service always needs a network for its operation Whereas API does not need any network for its operation

There are two popular web services protocols, such as:

  • SOAP(Simple Object Access Protocol)
  • REST(Representational State Transfer)
SOAP(Simple Object Access Protocol):

SOAP is an XML-based protocol for accessing web services over HTTP. It has some specification which could be used across all applications. In other words, it is a definition of how web services talk to each other or talk to client applications that invoke them. The XML used to make requests and receive responses in SOAP can become extremely complex.

Part of the magic is the Web Services Description Language (WSDL). This is another file that’s associated with SOAP. One of the most important SOAP features is built-in error handling. An interesting SOAP feature is that you don’t necessarily have to use it with the HyperText Transfer Protocol (HTTP) transport.

soap-architecture

REST(Representational State Transfer):
  • The architectural style for developing web services,
  • Popular due to its simplicity and the fact that it builds upon existing systems and features of the internet's HTTP in order to achieve its objectives
  • REST-based interactions all communicate their status using standard HTTP status codes
  • REST is also a language-independent architectural style
  • RESTful web services can be written using any language
  • REST is its pervasiveness

rest-web-services-architecture

Difference Between SOAP and REST:
SOAP REST
SOAP is a standards-based Web services access protocol that has been around for a while and enjoys all of the benefits of long-term use. Originally developed by Microsoft, SOAP really isn’t as simple as the acronym would suggest. REST is the newcomer to the block. It seeks to fix the problems with SOAP and provide a truly simple method of accessing Web services.
SOAP is a more rigid set of messaging patterns than REST. REST is an architecture style does not require processing and is naturally more flexible.
The rules in SOAP are important because, without these rules, you can’t achieve any level of standardization Both SOAP and REST rely on well-established rules that everyone has agreed to abide by in the interest of exchanging information
Language, platform, and transport-independent (REST requires the use of HTTP) No expensive tools required to interact with the Web service
Provides significant pre-build extensibility in the form of the WS* standards Efficient (SOAP uses XML for all messages, REST can use smaller message formats)
Automation when used with certain language products Fast (no extensive processing required)

Rest API Architecture

Rest API is form to access web services, it is basically a set of operations, where the developers can request and response via the HTTP protocol, let us consider the Rest API architecture, It has different Rest clients like Android, iPhone App, Browser, etc. But all of these rest clients have to connect to the App server(Backend Server) where we are making the rest request.

The Rest clients are making the request in the form of JSON/XML and these requests are converted into HTTP calls via Rest API, In the same way, the Backend server responses in the form of HTTP and the Rest API converts it into JSON/XML form and provide to the respective clients.

The Rest API is a platform-independent, the only thing we need is we have to request in the form of JSON/XML and receive the response in the form of JSON/XML.

rest-api-architecture

How to Build a Rest Request URL

We need an address of the rest API, this address is known as an endpoint. To build the rest request we need to know below three points :

  • What is an End Point
  • What are the types of rest request
  • What are Headers and Cookies
End Point:

The Endpoint is an address of the Rest API, the address is further divided into three parts:

Base URL: It is the website we are trying to reach

Example: https://www.expedia.com

Resource: This is the place where we are trying to reach inside the base URL.

Example: Inside the Expedia, we have several options called Cars, Cruises, etc are called resources.

Parameters : If we search for cars in any particular location then that is nothing but a parameter.

car-resource-under-expedia

So the endpoint contains BaseURL/Resource?Parametrs, we have to give the data in the form JSON and XML but the data in some condition can be given in the form of the endpoint. Go to Expedia and give some time and date and click on the search.

endpoint

If you observe in the address path in the above image after the question(?) mark everything will be a parameter. as it contains the base URL, Resource and parameter. This is how we are going to build the Rest API URL.

Different types of Rest Requests

Get Request: The Get request is used to retrieve resource representation or to get the information on the server. The Get request does not change the state of the resource and hence these are said to be safe methods.

If the Request-URI refers to a data-producing process, it is the produced data which shall be returned as the entity in the response and not the source text of the process, unless that text happens to be the output of the process.

For any given HTTP GET API, if the resource is found on the server, then it must return HTTP response code 200 (OK) – along with the response body, which is usually either XML or JSON content (due to their platform-independent nature).

In case the resource is NOT found on the server then it must return HTTP response code 404 (NOT FOUND). Similarly, if it is determined the GET request itself is not correctly formed then the server will return HTTP response code 400 (BAD REQUEST).

Post Request : The Post Request is used to create a new subordinate resource. Ideally, if a resource has been created on the origin server, the response SHOULD be HTTP response code 201 (Created) and contain an entity which describes the status of the request and refers to the new resource, and a Location header.

Many times, the action performed by the POST method might not result in a resource that can be identified by a URI. In this case, either HTTP response code 200 (OK) or 204 (No Content) is the appropriate response status.

Responses to this method are not cacheable unless the response includes appropriate Cache-Control or Expires header fields.

Please note that POST is neither safe nor idempotent, and invoking two identical POST requests will result in two different resources containing the same information (except resource ids).

Put Request: The Put request is used to update the existing resource. (if the resource does not exist, then API may decide to create a new resource or not). If a new resource has been created by the PUT API, the origin server MUST inform the user agent via the HTTP response code 201 (Created) response and if an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request.

If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale. Responses to this method are not cacheable.

Delete Request: The delete request is used to delete the resources. A successful response of DELETE requests SHOULD be HTTP response code 200 (OK) if the response includes an entity describing the status, 202 (Accepted) if the action has been queued, or 204 (No Content) if the action has been performed but the response does not include an entity.

DELETE operations are idempotent. If you DELETE a resource, it’s removed from the collection of resources. Repeatedly calling DELETE API on that resource will not change the outcome – however calling DELETE on a resource a second time will return a 404 (NOT FOUND) since it was already removed.

If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale. Responses to this method are not cacheable.

Patch Request: The patch request is used to make a partial update on the resource. If you see PUT requests also modify a resource entity so to make more clear – PATCH method is the correct choice for partially updating an existing resource and PUT should only be used if you’re replacing a resource in its entirety.

Please note that there are some challenges if you decide to use PATCH APIs in your application: Support for PATCH in browsers, servers, and web application frameworks is not universal. IE8, PHP, Tomcat, Django, and lots of other software have missing or broken support for it.

Idempotent Methods :
The term idempotent is used more comprehensively to describe an operation that will produce the same results if executed once or multiple times. Idempotence is a handy property in many situations, as it means that an operation can be repeated or retried as often as necessary without causing unintended effects.

Headers in Rest Request

Every request header must contain three HTTP header fields such as Accept, Content type, and Cookie.

Content-type: The Content-type header describes the FORMAT of the Body of your request is being sent, the body of the request can be sent by either JSON/XML but we need to declare in the content-type header which one we are using. This header is required in all the requests.

A request is any query made by your application to expects one of these values as the Content-Type header:

  • To send JSON in a request, use the application/JSON.
  • To send XML in a request, use the application/XML.

Accept Header: The accept describes which format you want a response body to arrive as. the response can be delivered either as XML/JSON by modifying the accept header. This header is required in all requests.

A response is any reply from to your application. expects one of these values as the Accept header:

  • To receive JSON in a response body, use application/JSON.
  • To receive XML in a request body, use application/XML

Cookie Header: The cookie header contains the authenticated session-id that you obtained after creating the REST API session. Having this header with the session ID allows your subsequent request to be authenticated. Without the Cookie header, you will receive a 401 Unauthorized error on any request attempts.













Comment / Suggestion Section
Point our Mistakes and Post Your Suggestions