What are APIs, how do they work with example

An Application Programming Interface (API) is a set of functions, procedures, methods or classes used by computer programs to request services from the operating system, software libraries or any other service providers running on the computer. A computer programmer uses the API to make application programs. Types of API include web services API like the Twitter API, which allows programs to use the API to receive updates on tweets.
- Wikipedia

You might also have listened about Windows API or Android API. API term is also used in Frameworks. What they do is make our life easier by providing simple callable functions and data we can use to communicate with them or perform a task. The implementation mess is hidden from us. So we don't need to make the whole system from scratch. Windows APIs can be used to make windows applications which communicate with Windows OS in the background. Same for Android. In case of frameworks, they also make our life easier. If you are developing a Web-application, you don't want to code whole authentication system yourself, because the Web-frameworks provide such APIs which are implemented using standard security practices.

Now, let's move to an example. Suppose you are building a Website which helps user search hospitals at an entered location. Now what you need is hospitals data (their locations, names and opening hours). For that, going and asking them and putting that in your database and using it to search won't be a good idea. What you need here is location searching API. Google Maps has such types of APIs. You can get place search results, photos, address, etc. In the next section I will cover how to fetch Hospitals at a given location using Google Places API.

Software, libraries or frameworks let you use their APIs (functions). But, in case of Web-services or say Web APIs provided by others is mostly exchagned using the secret API key they provide to you. Same is for Google Maps. We also need an API key from Google Maps, because we want to access their search data. Head to this link and get an API key.

We send requests to Web-services along with the API key and in turn they provide us response data. This data could be in formats like JSON or XML. We'll try to fetch JSON data. So, you need your API key in clipboard and paste it in the following URL below...

https://maps.googleapis.com/maps/api/place/textsearch/json?query=hospitals+in+vadodara&key=YOUR_API_KEY_GOES_HERE

Try to paste and go to this link in the browser and you should see JSON results. Example response:

{
   "html_attributions" : [],
   "next_page_token" : "CoQC_gAAAHdOTYDH8XmlIEGJleJH0GDeYGIbHrfDJgG0RB6NVxn3fpKRz9LKL5mGqUMa70NMPlbqOUkjdWxlRXV47oV8pVfYTNE_OuT9xrKbP6WwRGCSx6R_Ms-lfpnsCYCGuIb51-IH07Z6Ru3afw_uTN6--TFrEEyM7eRBXYm7Hzs1AdeEnQqhNNrjuNyKrp6Y52-zmYAtTDt16KuWEW54OyiioggW9mUrTpBqL38c-6D3Cf3-3c2CGu3Dtoca6Tc1H7S2yItEFw6zcYSk-EcHpWzjwcN3JK3BLVWzI8NsZaOxcGioLPyhbwX-obA9zpmtC_Iucsnc9NRwgBCY8p3UzQjFO1YSEO6xL_PEEYxeB6qxpAJG7ucaFOLpMT4oluEAR8VGR-JwNYFAnigQ",
   "results" : [
      {
         "formatted_address" : "Race Course Road, Opposite Inox Cinema, Circle West, Hari Nagar, Vadodara, Gujarat 390007, India",
         "geometry" : {
            "location" : {
               "lat" : 22.3127258,
               "lng" : 73.1588197
            },
            "viewport" : {
               "northeast" : {
                  "lat" : 22.31407562989272,
                  "lng" : 73.16016952989273
               },
               "southwest" : {
                  "lat" : 22.31137597010728,
                  "lng" : 73.15746987010728
               }
            }
         },
         "icon" : "https://maps.gstatic.com/mapfiles/place_api/icons/doctor-71.png",
         "id" : "a8f2c5fa79e2f8c311a3eaf32aba5762b7003f87",
         "name" : "Sterling Hospital Vadodara",
         "opening_hours" : {
            "open_now" : true,
            "weekday_text" : []
         },
         "photos" : [
            {
               "height" : 2000,
               "html_attributions" : [ "Photos are copyrighted by their owners" ],
               "photo_reference" : "CmRaAAAADTFMMb7OuH6wgclN7cpJ84HbfNHS0Sn2rquQzBcHpu3lt0Ecwh-PhbnrtCThoixKh_sEpRdsEHVo8vrDGAKxrwRPufBSHGpOkSzLolpU3UiF6Ebt9gjkJEa5G8KRWlgMEhB87go_6dMh520_8ghrNjPkGhTCmKWszspuuNO7gFLVVMV4VtOzqA",
               "width" : 2691
            }
         ],
         "place_id" : "ChIJD3RehbvIXzkRGf65nYMHB3A",
         "rating" : 3.1,
         "reference" : "CmRbAAAAVN9K_mFDuBzWhVNwT4sKCtiku8GhYCpz65-VKz8ErpqX2Kof-KiyMY4iw3cXiYbEgwftvGvyFig7r6o5vmRE784PVTv2D3zfJ2XHn5yezHNLxgRjlfC-Np5W05HiEkOYEhDvybMSd-AILxW2Y1Z9kKd3GhStgMpKbwaJEmhiaDKdqFwiuT_Pag",
         "types" : [ "hospital", "point_of_interest", "establishment" ]
      }

Here I've only included one result, there will be several results in the results object. Look for name attribute, opening hours, ratings and photos, etc. which are useful to us as we wanted to make hospital searching website. This is how we request and get response search data using Google Place API. It is also called HTTP transaction. If you are curious seeing the URL above, refer the API docs.

Note: Google Place API comes with limited usage. Refer their pricing for more. The current limit is 1000 requests per day

Well this was an API use case from Google Maps. There are also other sites like fixer, instagram, twitter, facebook, yahoo weather which provide their APIs so that one can build applications which interact with them. For example, you can make weather application using data from yahoo weather API.

I hope now you have idea about APIs. The best way to understand something is build it.

Thanks for reading. Comments are welcomed.