What is OData? (Part-2)

In my previous blog, I discussed how the Internet works and gave an introduction to what is HTTP and the difference between URL and URI. IN this blog we will discuss REST-based APIs.

Previous Blogs in the series:

What is OData? (Part-1)

What is REST?

REST or REpresentational State Transfer is an architectural style that uses a simple and lightweight mechanism for inter-machine communication. It is an alternative to the RPC (Remote Procedure Calls) and Web Services.

REST is resource-based unlike RPC or SOAP which are action-based. In SOAP you will have a request to get material data whereas, in REST, the material will be identified as a resource using URI and then use HTTP verbs to determine which operation shall be performed on the resource. It is important to note here that it is possible to have multiple URIs pointing to the same resource.

Representation of the resource is not the resource itself but only a representation.

The term representation is how the resources are manipulated in a rest based architecture

Representations depicts parts of the resource state which are transferred between client and server is mostly JSON or XML format. The client will typically have enough information to manipulate the resource on the server.  For example, if a Person is modeled as a resource and there is a service to get contact information of a person then the representation that you will get of that Person would be Name, Address, and Phone details in JSON or XML format.

The Six Constraints

The following are the six constraints defined which are attributes of a RESTful API.

1. Uniform Interface

Uniform Interface is fundamental to the design of any REST-based service. The uniform interface simplifies and decouples the architecture, which enables each part to evolve independently.

What that means is that it should be possible to identify the individual resource in the request, for example using URI. Once the Client has a representation of the Resource then, it should have enough information to update or delete the resource. And that the Client should not assume that any particular action is available on a resource beyond those described in the representation received from the server previously.

2. Stateless

The Server should not contain any Client state. It is possible to process a request only if they are self-descriptive and that the request should have enough context to act upon. For example, if the Person resource address needs to be updated then it is required that the Client passes on the particular Person resource details in the request for which it has received the representation from the Server in the previous request. If the state has to be maintained, it should be at the Client side.

3. Client-Server

We have already established this constraint that the RESTful architecture is a Client-Server architecture. Resource representations are transferred between client and server. We should always keep at the back of our minds that the Client of RESTful APIs will not have direct connections to the Resources.

4. Cacheable

Another constraint on a RESTful API is that any response that is coming from the Server should be cacheable on the Client side. Caching could be implicit, explicit, or negotiable. Implicit and Explicit caching is self-explanatory whereas Negotiable caching means that the Server and Client agree on how long a representation can be cached on the Client.

5. Layered System

The constraint of the Layered System is closely related to the above two constraints of Client-Server and Cacheable. It suggests that the Client of a RESTful API should not assume that there will be a direct connection between the client and the server. There could be multiple layers of software or/and hardware in between the two. The Client needs not to know whom exactly it is talking to and whether a response is coming from the server or is accessed from a local cache. This improves scalability.

6. Code on Demand

This constrains suggests that it should be possible that a Server can extend a Client temporarily. It means that the Server can transfer logic to the client as a representation to be executed at the client.

This is the only optional constraint.

A RESTful service needs to adhere to all of the above-mentioned constraints (except Code on Demand) to be called as a RESTful API.

Having covered HTTP and REST-based services we will cover OData in my next blog.

Next Blog: What is OData? (Part-3)

What is OData? (Part-1)

OData Introduction

This series of blogs is an attempt to provide a comprehensive guide to OData and how it is consumed in the SAP world. There has been a lot of content on the Internet explaining what is OData, how the services and published, and how to consume which is scattered and assumes that the reader has clarity already on some very important fundamentals. However, there are so many aspects that deserve more than just a mention. In this blog, we will try and cover the topic of 360 degrees.

We start with the very basics of HTTP and then gradually build on to OData and finally conclude with a detailed end-to-end exercise on how to create an OData service and how to consume it.

How Internet Works?

It might sound to be an unrelated topic when the focus is on OData. HTTP is the common thread between the two. HTTP is the underlying protocol on which OData is based and also one of the most common languages which is spoken on the Internet.

You would typically need a Web Browser, address of the document you want to read, or the URL (Uniform Resource Locator), a Web Server running at the system where the document is located.

Web Browser is a software that is responsible for retrieving and presenting resources on the web. Web Browser parses the HTML response received from the Web and prepares a DOM Tree. DOM stands for Document Object Model and it is a language-independent convention of representing objects in HTML. Web Browser acts as an interface between you and the World Wide Web.

You can request for a document located somewhere on this planet by providing its address via the browser which sends HTTP requests to the webserver. The Web server then sends back HTTP response that is parsed by the Web Browser for you to view the document on your machine.

HTTP stands for HyperText Transfer Protocol and as the name suggest it defines the semantics of what the browser and the web server can communicate to each other. The how part of the communication or the byte by byte transfer of the data packets across the network is not HTTP but it is done via TCP/IP protocols.

An important component in the story so far is also the Web Server. In a nutshell, Web Server is a server program that sits on a physical server and waits for requests from a client. Whenever a request is received the Web Server prepares a response and sends it back to the client using the HTTP protocol. It is important to note that HTTP is not the only but, by far the most commonly used protocol and that the client here can be a browser or any other software that communicates in HTTP.

Let us now try and put up a formal definition of the HTTP.

“HTTP is based on a Client-Server architecture style and it uses a stateless request/response protocol to communicate between the client and the webserver. The HTTP protocol helps define what requests can be sent across by the client and the response sent by the webserver. The communication of data over the network is however done using on TCP/IP protocol”.

It is evident that HTTP is based on client-server architecture from our description till now, the browser is the client which sends HTTP requests and webserver which sends the response back to the browser. But, why stateless?

Every single HTTP request that is received by the webserver is forgotten after a response has been sent across. Web servers do not process an HTTP request by remembering the previous request. 

URI and URL are not the same thing

We mentioned a while back that you need to know the URL of the document you wish to view in your browser. Can I not mention a URI as an address to get the document on the web? Let us quickly understand the difference between the two.

URI or the Uniform Resource Identifier can be classified as a name, locator or both that identifies a resource uniquely.

URL (Uniform Resource Locator) is actually a subset of URI that not only identifies a resource uniquely but also provide means of locating the resource.

Defining the Request and Response

HTTP requests are sent with one of the defined Request Method that indicates the action to be taken on the resource. Following are the two most commonly used methods:

GET

This is used to retrieve information of the resource from the server.

POST

This method is used to send data to the server.

For example, if you enter a text string on the Google search page and press enter, it will generate an HTTP Request with the GET method in the background. On the other hand, if you provide your username/password on a Login page and press enter a POST HTTP request will be sent to the server.

HTTP Response from the Web Server comes with data and the status code. The status code provides a context to the response. For instance, if you do not correctly provide the resource location, the web browser will send you a response which you are not expecting. Along with the data response comes the status code, known universally in the HTTP world, that explains to the user what could be the reason for an unexpected response.

HTTP codes are 3 digit integers.

Code and Description

1xx: Informational It means the request has been received and the process is continuing.

2xx: Success It means the action was successfully received, understood, and accepted.

3xx: Redirection It means further action must be taken in order to complete the request.

4xx: Client Error It means the request contains incorrect syntax or cannot be fulfilled.

5xx: Server Error It means the server failed to fulfill an apparently valid request.

For example, status code 400 means Bad Request. It means that the server did not understand the request.

OData allows the creation and consumption of RESTful APIs. In the next blog, I will cover what are RESTful APIs as the next stepping stone towards understanding OData.

Next Blog: What is OData? (Part-2)