What is API?
API stands for Application Programming Interface. It is a set of subroutines, protocols, and tools that define methods of communication between various software components . Each such software component has specific commands and format to perform the communication - hence the need for having clear API documentation.
The communication can take place on a specific computer (for example a piece of software talking to the operating system) or over the web. With the later we usually refer to a client’s computer sending API requests to a server.
This is indeed similar to web surfing with your favorite browser. But instead of getting predefined multi-media HTML web pages or an application functionality as your output, an API requests will usually only return pure data from the server or perform one specific service. In certain situation this is just more efficient and by combining different API commands you can perform sophisticated server operations.
Let’s illustrate this with an example. Telebroad’s Teleconsole is a powerful web-based telecommunication hub. Let’s say you want to copy all your contacts from your Teleconole account. Using your browser you will have to click on each contact and copy-paste it to a text document. This can be very time consuming. But instead, using a single API request you can have the Teleconsole server send you all your contacts in mere seconds as one text document.
What is REST API?
REST stands for REpresentational State Transfer. It is a kind of API that is specifically designed as a web service. A web service, very simply, is a protocol that allows a program to communicate directly to a web page, without needing to use a browser or having a user interact with the page.
We already illustrated this above talking about getting contacts from the Teleconsole. Extending on this a bit, we can say that instead of using your browser to communicate with the Teleconsole's web page, you would use an API client program to send an API request to the Teleconsole initiating a communication in the form of a web service.
Another example - you can get a weather for your local city from a weather forecasting website using a web browser. You will need to go to the web page and enter the name of your city. But if you know the REST API command for this website, you will get the data faster (assuming you have typed it before). You can even create a small program that displays this data automatically for you, essentially functioning like much like a weather app on your smartphone.
Basically we are still talking about a web server sending data over internet connection, but with REST API you can bypass using a web browser and perform specific operations more quickly.
There is a good website where you can experience real weather API with a convenient interface. It also works on many other popular websites and can give you valuable understanding of API functionality and usage.
REST API formats
When typing a URL address or clicking on a web page you are sending a request to a web server that in turns return a resource - another web page, a picture, a video etc to your web browser. The communication is performed using the HTTP protocol - Hyper Text Transfer Protocol. The data that the server sends back is written in HTML - HyperText Markup Language. HTML is the internet's standard for website creation since its foundation . Your browser reads the HTML code and uses it to displays the resources accordingly in the form of a web page.
Java is an object oriented programming language. Objects are pieces of software that perform certain function. When your browser receives a JSON code in response to a REST API request it does not get the object (or resource itself), but its representational state. Simply put that means JSON gives you the value of the object.
Let's put this all together now with the weather example from above:
- You will be sending a REST API request to the web address of the weather forecasting server using the HTTP protocol.
To send the request you will entering a code into a web browser address bar.
(Note this is a hypothetical example. No such real sever exists)
The code includes the "get" method. It is a REST API method for reading data.
There are other methods for changing data. We discuss this in more details here.
The code also includes some parameters specific to this website. You will need to read the site's API documentation to know about them.
- W=2459115 is the location information for New York City. It is in a WOEID format (Where On Earth Identifier).
- U=f designates that the temperature units are requested in Fahrenheit.
- Based on the parameters you provided, a certain Java program (object) on the sever will fetch the relevant data from an external sensor.
- The Java object will now contain the requested temperature value.
- The server will send you back this value in the form of JSON code that will look something like this:
"date": "Tue, 22 Aug 2017 02:00 AM PDT",
"text": "Mostly Clear"
Note that in addition to temperature other object values are also returned. It is nice to know that the sky is "Mostly Clear", but not all of these may always be relevant to your needs. You will quickly learn how to exclude data that you don't need in order to simplify the JSON responses.