API Crib Sheet
This page will attempt to explain the purpose and generally how the API will work.
Analogy
A political junkie named A. Pi sits by the phone and receives calls from people requesting information. A. Pi is really a functional autistic and can answer questions only from an approved list. The list changes frequently, and each caller has a copy of this list so they know what to ask and how to ask it. He has caller ID, and when picking up the phone and hearing the question, e.g. "Hey A. Pi, what are the candidates in the NY State Legislative Election of this year," he asks the caller for their password (each caller has their own) and, if the password is correct, he answers the question. If someone calls too often or otherwise becomes a problem, he will stop answering their questions. Anyone can lookup A. Pi's number, he's in the book, and when he sees someone call from a phone number he does not recognize, then he will provide them with their own password for that phone number.
General
The API will allow people outside our organization to integrate our data into their applications. An application could be a website, standalone program, or pretty much anything in the computer world. The API will respond to simple requests for data, such as 'get bio information for candidate Y' and 'get Votes for candidate X.' Each type of request (get bio, get votes) has to be planned for, and the initial release of the API will provide the responses for what we expect to be our more frequent requests.
How They Gain Access
A valid key is required to access the API. The registrant will apply via our website for a key. The sign-up process will require a valid email address and the host or machine which will use the key. This key will be a unique identifier to the registrant and machine, and so only one machine per key is allowed to access our data. Any problem API users can be blocked by revoking their key, and we have designed it so that a stolen key does not result in access - the host associated with that key would also have to be stolen.
Widgets
PVS will provide multiple things for people to use to gain access to our data. We will provide 'widgets' which are essentially completed code that we provide so the users can just cut and paste it into their website. This will be the easiest way for users to integrate our data. Widgets are built on top of the API and will require a valid key.
Libraries
We will also provide libraries, which are pieces of code that will directly connect to our servers through our API interface. This does not give them raw access to our database but a controlled access where we provide the data in a way we think will be useful to the users. This is the most powerful way for an outside entity to access our data but it does require some technical ability.
Multiple libraries will be provided so outside developer can work with their preferred programming language. If necessary, we can also provide documentation on our API interface so developers can create their own libraries.
CategoryAPIPlanning
