Working with Your First JSON based API

So you want to work with an API?

Maybe you're just starting to experiment with asynchronous JavaScript and you're wondering now how you can start making use of what you're learning in conjunction with an API to build a small project or app. To start, an API, or Application and Programming Interface, is justing something which allows communication between two programs. Before booting up your text editor of choice and trying to plow through a ton of data the hard way - you can spend some time just working with your browser and your browser console to cement your understanding before writing a single line of code.

Browser Extensions

For people using Chrome or Chrome based web browsers, it can be helpful to get a couple of extensions added in to your browser before starting this process. I like JSON Formatter which will help make the JSON (or JavaScript Object Notation) string format that we'll be looking at easier to read. There are others extensions as well that will make your data easier to read. The second, and far more optional, is Moesif Origin & CORS Changer. This extension can prevent something called a CORS error from happening if you are querying from the browser console. This is far more likely to occur once you are actually coding your app so you you may never need it for what we'll focus on for now, but if you see a message like this:

Cross-Origin Request Blocked: The Same Origin Policy disallows
reading the remote resource at https://url-location. (Reason:
Error Message and additional Information).

the extension should help clear it up!

Acquaint Yourself with Something Called a Query String

A query string is part of the URL structure that assists with setting parameters for your request and can be seen whenever you are searching for something in your browser. For a quick example, open up a new page and go to a search engine of your choice. I would recommend DuckDuckGo over Google for this one, because DuckDuckGo will be easier to parse as it returns the same search for every user regardless of what they enter. Google's search adds ... well ... feel free to take a look after the DuckDuckGo example.

Type anything into your search bar, hit enter, and then look at your URL.

https://duckduckgo.com/?q=cool+APIs&atb=v274-5__&ia=web

For now, just focus on the "?q=cool+APIs" portion of your search. Look at least somewhat familiar? The '?q=' portion represents your query and the rest is going to be whatever you typed in! While not all query strings start with ?q=, it is a common variable naming convention, and it will be important to note if your API handles direct queries.

The next part of the query is '&atb=v274-5__&ia=web' . If it looks like hot nonsense, take a moment and just focus on the '&atb=v24-5' and '&ia=web' portion. It's following the same pattern as our initial search - just with a slightly different syntax. These are additional parameters that DuckDuckGo is passing at the same time it passes our initial query! When working with your API, you can often see similar paths or routes, which will frequently be marked as '&foo=' or possibly '\foo' if it is part of the URL path itself. The idea is similar either way. When you get to the next step, be thinking about what structure it wants you to follow when you request its data.

Now .. you can do the same with Google .. but I wouldn't recommend it.

1)Find an API

There are countless APIs that can provide all kinds of data, but don't start by jumping into the deep end if this is your first time. Start with something small and relatively simple like the Jokes API free version. If you're feeling ambitious, you can try the Pokemon API. Other similar options that will have a lot of data to work with include TV Maze's API or some of ProPublica's free options.
For the time being, you'll want to stay away from any APIs that require authentication for access. You can work on API-keys and OAuth at a later time.

2)Read your Documentation

If you're starting off with a lightweight API this might be very easy. Make sure you know what the primary URL address is, and then start seeing how their end-points have been set-up. These will be ultimately be where you send your fetch request.

If, on the other hand, you're working with something that has a lot of data, the ability to get the data back in multiple formats like XML, or has a lot of parameters or paths available for accessing the information (for example, ProPublica's non-profit API has search parameters for pages, by state, by category, by 501 designation, etc), make note of them, and start thinking about how much of the data you might want to work with for your first project (and making sure you're querying in a way that will return JSON!).

Know that while there are conventions when working with these APIs, every API will be set-up differently. Be sure to also take note of any rate limiting (how frequently you can make requests either per second, day, or other measurement) your API of choice might have in place. Also, when you do get to the actual coding part, be thoughtful while testing your get coding so that you don't - say - call the end-point in any kind of infinite loop.

Odds are high that they're not going to let you keep doing that. Just remember that these are free resources that are letting us experiment, explore, and work with their data.

If you don't understand everything or one part of it after your first pass - that's fine because the next step is:

3)Reread the Documentation

Seriously - this will save you time. It can be tempting to just start diving in and trying to brute force your way through it. The documentation may or may not be dense but the more time you spend with it, the easier it will become. And the more you work with and understand one API, chances are that much higher it will pay off for the next one you want to work with.

4)Now Start Playing Around

If you have the JSON formatter extension installed, the easiest thing to do is to take the endpoint and throw it straight into your browser's http/search bar. Though you may be new to JSON, if you've made it to asynchronous JavaScript, you will likely recognize the way the data is being stored. You will be looking at a combination of nested objects and arrays that use almost the same syntax as JavaScript. You may be looking at a large swatch of many sets of data, or you may be looking at other routes or paths that you can start digging in to.

Using the knowledge that you gleaned from your documentation, you can start trying out your query strings and path options in the browser. Start by figuring out how you can access either the first piece of the data available to you or any one small section of the data. On some, it might be as simple as adding an id number like one at the end of a path:

http://api-url/apipath/1

While '1' might seem rather simple, the idea holds up in . For example to view Propublica's tax records from within it's own API (meta - right?) you could throw this in your browser:

https://projects.propublica.org/nonprofits/api/v2/organizations/142007220.json

It's a longer string but one that follows the preceding format. Others will let you search by name which will often provide a ?q= or ?query= path to note.

By the way - if you look at that Propublica data set or any other and feel a panic at the amount of data that exists - do not be overwhelmed! When you're starting out, you do not need to use every piece of data that every point offers - you just want to familiarize yourself with the form and get accustomed to working with it!

If you start looking around and you start running into something like this:

{"status": 404,
 "error": "Not found"
}

That's okay! As Obi-Wan never said, "These aren't the end-points you're looking for." Go back to the documentation and make sure that you're understanding your pathing and checking your query strings where appropriate.

Once you have that first piece of data, you can open up your browser's devtools (function+F12 works for most browsers/operating systems). For the moment, make sure you're entering the following code in the console on the same page as the end-point you're going to use as fetch requests from an outside domain may be automatically blocked. Navigate to the console portion of devtools, edit the provided URL location below, and throw the following code in:

fetch("your-entire-url-here-passed-as-a-string").then(r=>r.json()).then(console.log)

You should see the same object - but now you can start working with it in your text editor! The fetch() command (which amusingly enough, is a web API itself), when using it for a 'GET' request, works in a similar fashion as when you're making a request from your browser. After that, the first .then() statement helps us parse the JSON structure into a JavaScript data structure, and then the second .then() logs that sweet sweet data to your console. Congrats! You now have your first line of code and can start focusing on the fun things you want to do with it.