##Sunlight's APIs
- Sunlight's APIs
- Sign up for a key here!
- The Sunlight API Query Builder see the Open States example = Great!
Sunlight's Tools built w/ our APIs:
##What's an API?
The HTTP stands for HyperText Transfer Protocol. HyperText is text with links in it (like this!) and a transfer protocol is a fancy way of saying "rules for getting something from one place to another." In this case, the rules are for transferring web pages to your browser. We can use HTTP to grab just about any web page on the Internet. But where do those web pages come from? They come from other computers on the Internet called servers.
The Internet is full of clients (like you!) who ask for various resources (web pages, files, and so on), and servers, who store that information (or know where to get it). When you make an HTTP request, it zips through the Internet until it finds the server that knows how to fulfill that request. Then the server sends a response back to you!
In fact, this client/server relationship is a prerequisite of a set of principles called REST (or Representational State Transfer). This sounds kind of scary, but it's super easy—let's walk through it together.
Remember how we said HTTP involves sending hypertext (text with links)? Whenever you navigate through a site by clicking links, you're making a state transition, which brings you to the next page (representing the next state of the application). That's it!
By following this simple model of clicking from page to page, you're starting to follow REST principles. When something follows REST principles, we say that thing is RESTful.
An API, or application programming interface, is kind of like a coding contract: it specifies the ways a program can interact with an application. For example, if you want to write a program that reads and analyzes data from Twitter, you'd need to use the Twitter API, which would specify the process for authentication, important URLs, classes, methods, and so on.
For an API or web service to be RESTful, it must do the following:
- Separate the client from the server
- Not hold state between requests (meaning that all the information necessary to respond to a request is available in each individual request; no data, or state, is held by the server from request to request)
- Use HTTP and HTTP methods (as explained in the next section).
What are the four commonly used HTTP methods ("verbs")?
- GET, POST, PUT, DELETE
Endpoints are API-defined locations where particular data are stored. Just as you'll GET a pair of pants from PantsWorld or you'll GET a bag of peanuts from PeanutHut, you'll GET something different depending on the endpoint you use. For instance, if you're using the API for a video hosting service, there might be endpoints for the most popular videos, the most recent videos, or videos belonging to a certain genre or category.
Many APIs require an API key. Just as a real-world key allows you to access something, an API key grants you access to a particular API. Moreover, an API key identifies you to the API, which helps the API provider keep track of how their service is used and prevent unauthorized or malicious activity.
Some APIs require authentication using a protocol called OAuth. We won't get into the details, but if you've ever been redirected to a page asking for permission to link an application with your account, you've probably used OAuth.
API keys are often long alphanumeric strings. We've made one up in the editor to the right! (It won't actually work on anything, but when you receive your own API keys in future projects, they'll look a lot like this.)
A successful request to the server results in a response, which is the message the server sends back to you, the client.
The response from the server will contain a three-digit status code. These codes can start with a 1, 2, 3, 4, or 5, and each set of codes means something different. (You can read the full list here). They work like this:
1xx: You won't see these a lot. The server is saying, "Got it! I'm working on your request."
2xx: These mean "okay!" The server sends these when it's successfully responding to your request.
3xx: These mean "I can do what you want, but I have to do something else first." You might see this if a website has changed addresses and you're using the old one; the server might have to reroute the request before it can get you the resource you asked for.
4xx: These mean you probably made a mistake. The most famous is "404," meaning "file not found": you asked for a resource or web page that doesn't exist.
5xx: These mean the server goofed up and can't successfully respond to your request.
##Ways to Use Sunlight's APIs
Project Inspirations using Sunlight Foundation APIs Need some help getting your creative juices flowing? Here are some inspirations for projects using our APIs.
Influence Explorer: Build a demo app that lets users pick an election cycle in any state, and then browse the available races and see what industries supported each candidate. Work on a natural language search tool that lets users ask the data things like "Who is the best fundraiser in Congress?" and get an answer.
Political Party Time: Create an interactive data visualization that combines fundraisers with Yelp reviews to determine if there’s a correlation between well reviewed restaurants and the number of fundraisers they host. Set up a twitter bot to tweet at members when they are at fundraisers with pre-populated messages like: How’s the steak paid for by XXX (company)?, How much is that plate?
Congress: Create an easy to use Congress (and state with Open States) Lookup tool to find your representative and contact them directly (via email, phone, twitter, address). Create Twitter bots that would sniff out whenever someone tweets about a politician or a bill and the bot replies: “Wanna know more about Rep. X, or Bill Z”? Redirect them to a Sunlight tool using this API (either Congress or Influence Explorer). A tool that allows you to upload a photo of yourself to see which member you look like (based on member photos).
Open States: Use Open States API to look up legislation and a particular representative’s connection to a specific bill (whether through voting or sponsorship) and committees they are assigned to in order to figure out if the topics they are interested in are the same topics the user cares about. Develop automatic processing and categorization with Open States that allows for bill searching by extracted entities. Combine available information about your state rep and legislative data with information from Open States (just like these guys did.)
Capitol Words: Construct vector space model of members of Congress using most frequently used terms by each lawmaker and cluster based on similar usage.
Docket Wrench: Connect Docket Wrench metadata with data about economic significance from OIRA's reginfo.gov and look for patterns: do economically significant rulemaking proceedings attract more comments? Do they attract more form-letter behavior, or more comments from big industry players? Use the distinguishing phrase data from Docket Wrench's clustering analysis to try and identify form-letter authors by looking for occurrences of that text elsewhere on the Internet (e.g., on the website of the organization that ran the campaign).
Multiple APIs: Mash-up data from Open States, Influence Explorer and Congress to make it easier for anyone to group legislators by common identifiers (such as age, state, committee, gender, membership in a caucus, years in Congress) and then look for patterns in either the bills they sponsor, the money they receive, or what they say on the floor. Create wordpress plugins or Javascript widgets that are embeddable in any HTML page to show and/or look up congressional information, track bill status, track new bills, political parties, or anything related to a particular keyword.
Need more inspiration? Check out these external projects using Sunlight APIs*
Capitol Words was used to compare vocabs of each party. Android app for studying US Citizenship Civics test where some answers vary by user’s state and district. A call tool matching zip codes to legislators in order to get Congress to update the Electronic Communications Privacy Act. A project made during the Bi-Coastal hackaton DoesCongressReallySuck.com And learn more Sunlight APIs at hackathons: Hack Jersey, Bi-coastal Datafest, 2012 Election Hackathon, New York Times Hack Day
*Find many other examples of projects in our API Gallery.