The Underlying Hero in Modern Web

Before I wrote this blog I read some articles about API’s. That is because I need to develop a mental model to explain this technology in the simplest way possible. So I’m going to use a simple example to give an idea how an API works.

Let’s take this toy. It has a covering lid all around it with distinct types of holes and a person can only insert the appropriate object to that hole. This is also an API. It will take circles, triangles, and squares and lets them into the box. It forces the person to organize the inputs going into the box to the designer’s liking. But this is just a toy. It will force the person to put the correct object through the correct hole because that’s the target of this toy. But in a real software API designer will force because it is easy to provide return service if all the distinct requests come in a distinct way. Let’s define outside the box as the client/user environment and the lid around the box as the API for the system inside the box.

Let’s say that if the user pushes a square to the box, the internal system should return a circle and assume that there is a mechanism for that. The box will only send a circle if the user passes the square. This is exactly what happens in APIs. It will ask the input request in a designer defined format and if the client sends the request in the correct format the API will send the results. We can also identify API as a way of talking to that internal system. In current practical scenarios, the internal system that we defined in the above scenarios is usually a system that in a remote location. So to access that system we talk to the system in the format that is asked by the remote system. So if we want to give a more serious technical word for the above scenario we can say that it is abstracted. So even if the internals changes the it is totally unknown to the user and won’t affect the service that they expect from the remote system(unless designers change the abstraction too). This way, API forces structured data-based (or, in this example, block-based) exchanges between what the designer made and the outside world which wants to use it.

So the above scenario is the mental model that I first developed to understand what an API means?Then started to study in a more technical based way.

But we must understand one thing clearly. API is not a protocol. There is a huge difference between them. An API describes all the valid messages that one program can accept. It says nothing about the proper ordering of these messages or their interaction with other programs.(So even in the above toy it has described what type of valid blocks that it will accept. So it’s lid is an API giving access to its internals)

Protocols sit on top of APIs. A protocol describes the valid sequence of messages that flow between the APIs of multiple parties to accomplish some higher-level task. According to Wikipedia API means

a set of subroutine definitions, protocols, and tools for building application software. In general terms, it is a set of clearly defined methods of communication between various software components. It defines methods of communication between various software components and provides access to data of an operating system, application, or other services.

So by reading the above definition, we can see that the current mental model that we have developed yet is pretty accurate with it. Then I started to find out what are the purposes and uses that API’s will specifically provide. After reading some articles I have identified the following are generically more prominent.

Due to the abstraction API will simplify the programming. As an example API for file input/output might give the developer a function that copies a file from one location to another without requiring that the developer understand the file system operations occurring behind the scenes

We use GUIs (graphical user interface) to interact with operating systems, application software etc easily. APIs are similar to that, developers can build better products by using APIs because they need not to worry about underlying technology and don’t have to reinvent the wheel.

Now as we have a fine understanding about what an API is, let’s understand what are Web APIs

Web API

Modern web sites have adopted the above concept hugely. As in the diagram both client side and server side, there are APIs to communicate. The code will call the API appropriately and then communication will occur. First, let me explain about server side. Server side API is an interface with multiple endpoints (which I’m going to explain later )to a defined request-response message system. This is the interesting part almost all of these requests are passed as JSON or XML via WEB using the HTTP protocol.

Then as you can see we came over a word name endpoints. The endpoint is where resources lie that can be accessed by third party software. These are the places where external clients access usually. These locations have the resources that clients requests. As a characteristic, these endpoints need to be static. Because if the location of those gets changed then the client’s software will crash as because of the API change. But service providers have developed a version controlling system in order to update the APIs as an example https://api.clarifai.com/v1/tag/". The “/v1/” part of the URI specifies access to the first version of the web API. If clarified decides to update to version two, they can do this while still maintaining support for third party software that uses the first version.

In a client side, web API is a programmatic interface to extend functionality within a web browser or other HTTP client. These will be running on top of the JavaScript language and allow you to implement functionality more easily. Then as we have a platform to identify and contrast some web API and protocols. Let’s take two of the most popular ones.

First I’m going to talk about SOAP.

SOAP(Simple Object Access Protocol)

SOAP relies exclusively on XML to provide messaging services. Microsoft originally developed SOAP to take the place of older technologies that don’t work well on the Internet. One of the most important SOAP features is built-in error handling. If there’s a problem with your request, the response contains error information that you can use to fix the problem. Given that you might not own the Web service, this particular feature is extremely important. Otherwise, you would be left guessing as to why things didn’t work. The error reporting even provides standardized codes so that it’s possible to automate some error handling tasks in your code. SOAP has a more rigid set of messaging patterns. This is to achieve standardization. SOAP is also suited for more secure interactions.

REST(Representational State Transfer)

If you read forums or articles regarding SOAP in many you can find that developers found SOAP hard to use. For example, working with SOAP in JavaScript means writing a ton of code to perform extremely simple tasks because you must create the required XML structure absolutely every time.
So to overcome these hardships REST API came to the stage. REST provides a lighter alternative. Instead of using XML to make a request, REST relies on a simple URL in many cases. In some situations, you must provide additional information in special ways, but most Web services using REST rely exclusively on obtaining the needed information using the URL approach.
Unlike SOAP, REST doesn’t have to use XML to provide the response. You can find REST-based Web services that output the data in JavaScript Object Notation (JSON) and Really Simple Syndication (RSS). The point is that you can obtain the output you need in a form that’s easy to parse within the language you need for your application. As we can see this is a huge step forward and reduction of hardships.

Soap Vs Rest

Advantages Of SOAP

1. Language, platform, and transport independent.
2. Works well in distributed enterprise environments (REST assumes direct point-to-point communication)
3. Standardized
4. Built-in error handling
5. Automation when used with certain language products

Advantages of REST

1. No expensive tools required to interact with the Web service.
2. Smaller learning curve.
3. Efficient (SOAP uses XML for all messages, REST can use smaller message formats).
4. Fast (no extensive processing required).
5. Closer to other Web technologies in design philosophy.

Conclusion

Some people try to say that one process is better than the other, but this statement is incorrect. Each protocol has definite pros and equally problematic cons. You need to select between SOAP and REST based on the programming language you use, the environment in which you use it, and the requirements of the application. Sometimes SOAP is a better choice and other times REST is a better choice. In order to avoid problems later, you really do need to chart the advantages and disadvantages of a particular solution in your specific situation. There’s one absolute you should get from this article. Don’t reinvent the wheel. Use these technologies to develop complex web sites as your choice.