Overview of Web Services APIs, SOAP / REST

This post covers few key terms associated with Web services APIs and gives an overview of those.

API - Application Programming Interface, is like a contact or messenger that's provided by one piece of software to allow some other piece of software to communicate with it

There are lots of APIs, in computer's operating system, smartphones, websites, devices like refrigerators, washing machines, televisions etc.

Web services API is one type of an API, Web services API requests and responses are structured/formatted, most commonly used formats are XML(Extensible Markup Language), JSON(JavaScript Object Notation)

A website is meant for human consumption, where as a web service is meant for code / application level consumption

Two popular types of Web service APIs: SOAP and REST

Specifications in JAVA: JAX-WS for SOAP, and JAX-RS for REST

SOAP - Simple Object Access Protocol: XML over HTTP(S), since 1990s, heavy weight, not simple. SOAP is like an XML schema, it is not an application protocol and doesn't come with a port number.

Web services can be thought of as an implementation of SOA(Services Oriented Architecture)

In SOA, two pieces of software(service provider and service consumer) are communicating with each other

Provider <-----request/response-----> Consumer

In this 2 way communication, the service consumer sends service requests where as the service provider sends responses

In a Web services implementation, The service provider software publishes it's service descriptions which are placed in a directory, this is mostly done using WSDL(Web Services Description Language). The communication between the provider and directory happens using SOAP protocol. The consumer queries that directory and gets responses back, also using SOAP, to find out the list of services offered by the provider and the ways to communicate with the provider.

WSDL is a file written in XML language, a WSDL file tells what a web service does and how it can be consumed.

Based on the lookup of the specifications defined in the service descriptions, the consumer then sends request messages in XML format according to the need, the provider would also send responses accordingly in XML

The consumer software can be a software such as postman client or a code written in programming such as programming languages such as Python, Java etc. by importing appropriate libraries

The consumer can either consume data(HTTP GET) from an API, or write data(HTTP POST) into an API, all of the HTTP methods can be called over the API

HTTP Methods: GET(retrieve), POST(Submit, not secure), PUT(update), DELETE, HEAD(GET with out a body), OPTIONS(retrieve supported HTTP methods), PATCH(partial update)

The web services API relies on a stateless, client-server protocol, which is mostly HTTP(S) (Hyper Text Transfer Protocol)

We may need authentication in most of the cases to talk to an API endpoint(URL/URI) which is not public or open, most of the websites use OAuth2 for this purpose

username(client ID) + password(client secret) => access token

this access token will be used for all subsequent API Calls (HTTP requests)

REST - Representative State Transfer

REST API is also called as RESTful API

RESTful means that the particular protocol or API conforms to the REST architectural style, the world wide web is considered as the largest implementation that conforms to the REST standard.

REST is an architectural style, it's not a protocol, it's a set of architectural constraints you would see in a protocol(example: HTTP) built in that style. So, HTTP is a RESTful protocol.

REST is the architecture of the Web as it works today. A REST implementation can support both XML and JSON over HTTP(S). It provides a simple method of accessing web services.

70% of all public APIs are REST APIs. Google Maps' API, Twitter's status update API, Facebook's graph API, Instagram's Media Search API, are all REST APIs

The client is also called as the User agent, the Web server is also called as the Origin server.

There could be lots of HTTP intermediaries(not networking devices) between the user agent and origin server. The intermediaries can help in translation of messaging and can also improve performance using methods such as caching. Intermediaries can contain proxies chosen by the client and Gateways chosen by the server.

--end-of-post--