Demystifying APIs(Beginner’s Guide )

As a new coder, API’s can appear nothing short of scary. Have you ever visited an API documentation page and felt like this is what is looking back at you…

Been there!

Don’t fear, below I have outlined some key points about API’s and included some demos that should make them feel a bit more accessible.

An API (Application Programming Interface) is an intermediary that allows two applications to talk to each other. It acts as a messenger, delivering your request to the provider and then bringing the response back to you. You could think of it as a waiter, who takes your order from the menu (the documentation), brings them to the kitchen (the server) and delivers your prepared meal (the response). If for some reason the kitchen is unable to prepare your order, the waiter will let you know that your order is unavailable via an error message (return error = “Resource not found”).

One of the biggest challenges of working with an API is formulating your API call correctly in order to achieve the desired response. To improve your chance of success, it is important to understand the anatomy of the call.

As depicted above, API calls are made up of:

  1. The method — action you are trying to take (that corresponds to an HTTP verb -GET, POST, PUT/PATCH, DELETE);
  2. The endpoint — route/url/address/touchpoint of communication between applications;
  3. The Resource — database/website/application you are trying to access;
  4. The Header — this goes inside your call and has info about the call you are requesting/receiving. Check documentation for what this should look like.
  5. The Body — the response you get back(typically JSON)

Understanding this, the next thing to consider is AUTHENTICATION!!!

There are three levels of authentication to consider

i) No Authentication — no credentials necessary

ii) Developer Authentication— requires and API key and/or a secret. Depending on the API requirements, which can be found in the documentation for that API, you will need to pass in your credentials as a param, or inside of the headers.

iii)User Authentication(OAUTH) — allows a user (resource owner) to grant a third-party application (consumer/client) access to their information on another site (resource).

Here is a collective list of free APIs of varying authentication levels that you can play around with using the examples below.

  1. SURPRISE!! For Unix/Linux/Mac developers you can simply use the ‘curl’ command!

Run:

#api request w no authentication requirementcurl 'https://cat-fact.herokuapp.com/facts'#api request with dev auth req check documentation for header specificscurl 'https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=1500&type=restaurant&keyword=coffee&key=YOUR_API_KEY' 

2. Another user-friendly alternative is rest-client, a simple HTTP and REST client for Ruby. In your console run

gem install rest-client

Then, create a ruby file ‘test.rb’ with the below code.

require 'rest-client' 
require 'json'
url = 'https://cat-fact.herokuapp.com/facts'
response = RestClient.get(url)
parsed = JSON.parse(response)
p parsed

In your command line run ‘ruby test.rb’ to see the results(a nested hash). Visit the ruby docs to learn more about HASHES and how you can manipulate them.

3. Finally, for all your api needs try out these free, savvy and user friendly browser based clients POSTMAN or RAPIDAPI .

And now your scary monster is

Check out these additional resources to further solidify your understanding

https://developers.giphy.com/branch/master/static/api-c99e353f761d318322c853c03ebcf21b.gif

https://gigaom.com/2010/10/29/using-apis-not-quite-as-hard-as-it-looks/

https://code.tutsplus.com/tutorials/creating-an-api-centric-web-application--net-23417

https://www.twilio.com/blog/2015/10/4-ways-to-parse-a-json-api-with-ruby.html

https://medium.com/@sgg2123/apis-and-ruby-7675144f3391

https://www.theodinproject.com/courses/ruby-on-rails/lessons/working-with-external-apis

Full Stack Engineer — THIS CODE IS ON FIRE!!!