Basic API Development Part 1 - Importance, Theory and Hands-on with flask framework

on

Introduction

API stands for - Application Programming Interface. If you search Wikipedia or other such websites for definition of API, a number of complex terms such as 'web services', 'REST', 'computing interfaces', 'routines' , etc. will make you feel dizzy and you will end giving up. This blog aims at defining what an API is, simplifying the jargons surrounding this term, why should you learn it's basics, and developing and testing a basic API with tools such as flask, postman and curl.

Why learn about APIs?

Because you are surrounded with them. Whether you do a login or a signup, or book a ticket at a cinema hall, or surf through Trivago to find the best hotels - APIs are everywhere, and as a software developer, you may be required to develop one for your usage!

Recently, I also observed that some companies have started to ask some domain specific knowledge during the time of campus recruitment and one such recruitment round consists of an API development exercise where one has to implement basic API endpoints with required features. A lot of people focus only on data structures, algorithms and core subjects, and are not able to clear such rounds. A basic knowledge may help in making up the mind for such rounds.

Web Services, API and REST

Web services consists of servers that provide a specific service or a set of services to a user via internet. The client sends a 'request' and a server responds with a 'response' to the client. A response may consist of an HTML page, a json-formatted data or XML, depending on the type of service. The client does not directly access the services, but connects to an 'API Gateway' which depending on the nature of request, directs it to appropriate service.


API is a kind of abstraction which provides reusability of code. Let's say someone somewhere in the world has written a very useful piece of code and we call it a 'resource'. Other people would like to use that piece of code aka the 'resource' in a secure abstracted way and the owner of the resource may develop an interface through which only the functionality of the resource can be accessed by users and the owner may charge them for usage. This interface is what is called an 'API' of that resource.

The client connecting to an API is exposed to particular API endpoints (These are the endpoints where the client can send a request for a specific service, like a url). The client does not know the inner implementation of services, it is only concerned with the 'response' to it's request. The services on a web server may themselves be connecting to some other services via APIs to get the request processed. API is a set of rules that allow programs to talk to each other. The developer creates the API on the server and allows the client to talk to it.

Let's understand more clearly with help of examples. We have to book hotels for our vacation and we visit the Trivago android app to find the best and cheapest hotels. We enter the city name whose hotels we want to explore and we get a list of hotels as a response with prices from different websites such as MMT, goibibo and OYO. What's happening behind the scenes can be described with the diagram below.


  1. Our android application acts as an interface and sends a 'GET' request to an API endpoint say, 'https://....../hotelsList?city=Delhi' and waits for a response.
  2. The request reaches the API gateway of the corresponding endpoint where it is directed to the service which handles request to specified endpoint.
  3. The service starts processing the request for all the hotels in 'Delhi' by communicating with the APIs of other websites such as MMT and Goibibo which offer hotel rooms. Thus, we can see that the communication between different components occurs through API calls.
  4. The request for hotel lists is directed to specific database servers which send their respective hotels' list with other components such as their price, location, reviews, etc. in raw format(XML or JSON).
  5. The Service compiles requests by arranging the list, formatting it into a specific HTML/CSS layout, and sends a response to the client.
One can appreciate the use of APIs in seamless inter-connectivity of different components over intenet. The APIs may be free or paid-per-request. To prevent random attackers from making API calls, the APIs may first authenticate the users and issues them an 'API key' as a token of mutual understanding.

Another example can be that of the very famous 'Google Maps API'. Let's say you want to develop a food delivery application but you don't have the resources to launch a satellite in space and then track the delivery guys and the orders (everybody is not Elon Musk!!). But big giants out their such as Google have done this setup for you by building APIs through which you can access their google maps features by paying them a formal amount.

Almost All sites nowadays have features of signup and login using Google or facebook accounts. What's happening is this that instead for implementing a full authentication service by themselves and making their users go through the tedious process of sign-up, they authenticate the users by using their google or facebook accounts data. Google and facebook provide APIs for authetication and users just need an account to these websites to register on any website implementing their APIs.

Thus, APIs are interfaces offering code reusability, authentication and seamless connectivity. The formal definition may vary as per one's perception of the concept but this is the core of it. A lot of APIs of all sorts are available for integration in software on the internet used for login, signup, weather forcasts, music services, travel bookings and payments. The next section will deal with REST APIs.

'REST' - what does it mean?

REST is an architectural style one follows while developing APIs and web services. It is a set of constraints that one follows. Before discussing these constraints, let's clear some jargons and concepts :
  • An HTTP request can be of type 'GET', 'POST', 'PUSH', 'PUT', and 'DELETE'. These methods provide meaning for the request you’re making. They are used to perform four possible CRUD actions : Create, Read, Update and 'Delete'. More about CRUD operations here.
  • JSON stands for Java Script Object Notation and is a common format for sending and requesting data through a REST API. It is a simple key-value dictionary like format for sending and recieving data over internet.
  • Interoperability refers to the ability of systems to share and exchange web resources and information. APIs promote interoperability.
'Web resources' comprises not only of data, web pages or documents, but also any action, processing or change of a web-based entity. . In a RESTful Web service, requests made to a resource's URI will stimulate a response with a data payload formatted in HTML, XML, JSON, or some other format. The response can confirm that some alteration has been made to the resource state, and the response can provide hypertext links to other related resources.
REST stands for Representational State Transfer, meaning that the modified state of web resource is sent in the response, not the whole web resource or object.

Implementing a RESTful web service comes up with some constraints which a developer has to follow :
  • Separation of Client and Server: Client and Server are different entities, and they should evolve independently. Client should have access to only API endpoint URIs and that's all. All the processing of request is done at Server. This constraint is rather a generic one as the notion of Client and Server is common in web-development.
  • Statelessness: This constraint ensures that the HTTP interaction between the Server and the Client are 'stateless'. Let's understand this concept a little more. The constraint says that the server should not remember the state of the application. As a consequence, the client should send all information necessary for execution along with each request, because the server cannot reuse information from previous requests as it didn’t memorize them. To understand the notion of states and statelessness, I recommend reading this article.
  • Cachebility: Caching of data and responses should be implemented whereever possible as it reduces latency on client side as well as load on server side. There is a little tradeoff of consistency as cache may become stale, but appropriate policies can be implemented to mitigate this.
  • Uniform Interface: The API interface should follow some form of standard and should be uniform throughout. The resources exposed by APIs to consumers should be well defined, the API documentation should specify the response format as well as the parameters it is expecting as input. API versioning should be done so that any old user of your API can still work with older versions and may switch to newer version with minimal difficulty.
  • Layered System: The architecture allows layering of the system with multiple server and APIs and each component should be able to see up to the immediate layers only. Hence, transparency should be maintained. 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.
  • Code on Demand(Optional): In addition to static responses, servers can send a piece of executable code to be run on the client, hence extending it's functionality.
Another analogous architectural style to REST is SOAP(Simple Object Access Protocol). SOAP is more complex and offers more features and is beyond the scope of the blog. You can check out a comparison between REST and SOAP here.

Enough of Theory !! Let's start developing our very first API endpoint!!

Implementing and Testing basic API endpoints!!

We will demonstrate a very basic web server which handles CRUD operations request by client at specific API endpoints.

You need to install Python3 and Flask framework for this exercise. I recommend revising some basic python concepts such as how to import and what are decorators. You can install an IDE such as Pycharm or spyder for coding python scripts and projects as they provide a number of features for importing packages and debugging.
  • Create a python file name 'web_server.py' and go as follows.
  •  Import flask module and create an  app instance as shown above. __name__ is a special variable in python, it will equal to “__main__” if the module(python file) being executed as the main program.
  • Now we define different end point using @app.route() decorator. What this decorator does is simple - it executes the function following it when a HTTP request is sent to the specified endpoint. The end point we define in our demo web server are (these are relative paths) :
    • /readHello
    • /createHello
    • /updateHello
    • /deleteHello
  • The first parameter to @app.route() is the endpoint, while the second method refers to the type of request sent to the endpoint. For simplicity we just return a string as a response to the request.
  • Lines 25-27 mean that your flask app will be run if we execute web_server.py . Notice also that we are setting the debug parameter to true. That will print out possible Python errors on the web page helping us trace the errors. The app will run on http://localhost:5000.
  • We run the server using the IDE or command python web_server.py
  • We can test the server using either postman or curl.

Testing the API using Curl command line tool

Curl is an awesome command line tool for sending HTTP requests for testing APIs and debugging. People with love for linux commands will prefer this method. After installing curl using some suitable package, run the following command :

curl -i -X GET http://localhost:5000/readHello

This command sends a GET request to our endpoint /readHello and we will recieve the corresponding response containing response code, headers and our string message.


Curl has a number of options through which one can authenticate as well as send parameters to the endpoint if the endpoint has that functionality.

Testing API using Postman

Postman is an interesting tool for GUI fans and provides an easy-to-learn interface to send various requests to server and API endpoints. A typical request can be framed in postman as shown below. Postman is available for both linux and windows OS. Just specify the endpoint and the type of request and click the send button. The response will be available in the body tab.



So , where to go from here?

This article covers theory of APIs and how to create and test very basic API endpoints. Curl and Postman are powerful tools for sending requests. You can easily install these tools and IDEs based on your specific OS (you have the power of Google). In the example above, we return raw strings as response, but in reality much more data is sent in after performing necessary database actions. JSON is a popular format as it is simple to understand, There are various libraries available in all frameworks and languages for parsing JSON data. In the next part of Basic API development, a more complex service will be implemented using flask and tested using curl. Do subscribe the blog for notifications and comment down topics of computer science domain that interest you and want to learn more about!

Comments

Post a Comment