Skip to content

Instantly share code, notes, and snippets.

@konklone

konklone/intro-to-apis-notes.md

Last active March 4, 2016 07:00
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save konklone/9528a235c92120e8d93e to your computer and use it in GitHub Desktop.
Save konklone/9528a235c92120e8d93e to your computer and use it in GitHub Desktop.
Download ZIP
Notes for Intro to APIs workshop for Open Data Day, March 4-5, 2016
Raw
intro-to-apis-notes.md

Link to these notes: bit.ly/intro-to-apis-notes

Link to workshop handout: bit.ly/intro-to-apis

Links I'll use

Intro

URLs

JSON

APIs

Poking

Introduction

Before we begin:

  • Do you have a recent version of Firefox or Chrome?
  • Do you have a JSON viewer installed? Get that done now.

Also before:

  • Introduce myself.
  • Ask about proficiencies. Communications? Developers?

Okay:

  • De-intimidation of the Internet. Small parts, tiny patterns.
  • You will be empowered in your own work on the Internet.
  • An appreciation for what data actually is.

URLs: They use the exact same rules, but the viewer (location bar) is pretty terrible. That'll be the most annoying part of this workshop.

Data: If you've sent a spreadsheet instead of a doc, you get why data is good. We're going to go "up a level" from spreadsheets (to JSON), and then come back down.

APIs: they mean a lot of things. Web APIs, all the ones your colleagues are building and that you'll potentially encounter, are URLs that lead you to data.

We'll stay all in-browser, no code or terminal required.

URLs

  • How are URLs laid out? What's behind each piece?
  • Originally, URLs were just ways to reference files and folders
  • Go to flickr.com/search
  • Search for space [ go to slides ]

Okay, neat, but this is a little arcane.

Well, these URLs aren't designed for you to understand, they're just to make a little advanced search page. Now we're going to look at an API.

APIs, and JSON

On the web, APIs are just URL patterns, that lead you to data instead of a web page.

You've seen data at a URL if you've ever peeked at an RSS feed - and if you've ever hit View Source, then you've seen that web pages themselves actually are pretty data-like.

Could you have a CSV API? Absolutely. But that's pretty rare. Used to be XML, but nowadays the main data format is JSON.

JSON, via the Congress API:

The Congress API, step by step:

  • Let's read a bit about how the API works

    • /legislators, okay
    • error? okay...
    • Ah, we need an API key
    • opendataday key

  • Okay, /legislators

    • fold up 'results', look at what we have

  • Export that to CSV!

    • konklone.io/json/
    • now you have a spreadsheet of 20 members of Congress

  • Let's learn how to make this even better

    • let's limit the fields to what we want
    • let's drop the pagination
    • new spreadsheet: every member of Congress

What did we cover?

  • URLs: some things are universal to sites, APIs, etc. Some things are specific to that service. Now you know how to wield them, and recognize each part.
  • JSON: How to read JSON. You can sanity check your way through things, convert them to CSV, and know what people are talking about.
  • APIs: You can now understand a lot more from API docs than you used to. When you hear about an API launch, like perhaps openFDA, you can actually read it and understand how amazing it is more viscerally.

Take a look at what my old colleague Nicko did to make congressbdaybot

Conclusion

You can certainly do a lot more with data by writing code in a programming language. There's a limit to what you'll be able to do by poking around APIs and exporting them to CSV. Yet you can go a lot further than you expect, too.

And hopefully this demystifies some words for you: URLs, JSON, and APIs don't take a computer science degree to understand. They are patterns, meant for both humans and computers to understand.

Understanding how this stuff fits together will help you in seeing how the web works, the value in tools people make, and maybe even to know when someone is feeding you a line.

Above all: keep going! Anything the "tech people" do, you can do, with just a little courage and some time spent. Even if you don't change your career, basic skills with data, technology, and the Internet will set you apart and open up doors you didn't realize were there.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment