Demystifying APIs(Beginner’s Guide )

Raq Robinson
Nov 14, 2019 · 4 min read

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…

Image for post
Image for post

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.

Image for post
Image for post

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.

Image for post
Image for post
Method, Endpoint and Resource of an API call
Image for post
Image for post
Header and Body portion of an API 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!!!

Image for post
Image for post

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.

Image for post
Image for post
  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 .

Image for post
Image for post
https://www.getpostman.com/product/api-client
Image for post
Image for post
https://rapidapi.com/

And now your scary monster is

Image for post
Image for post

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

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store