The MyIGA Hypermedia API is a collection of technologies that provide information about the Indiana General Assembly.
This information is made available by the MyIGA API server - a network-based application - as a set of discoverable resources, to API consumer clients. You can write a consumer client in any network programming language that supports HTTP.
A consumer client can access this service by authenticating itself to the server, and requesting a representation of a specific resource; usually, the root API resource. A client may consume additional information by exploring the API and discovering further resources. These are revealed to the client by the server through the use of hyperlinks.
The server can present information to the client using several known formats, identified by their Internet media-types. The format is chosen by the server, in cooperation with the client making the request.
First of all, in order to be authorized to access a resource, a consumer client must include a valid authentication token in every request.
Using HTTP, this is accomplished by including the token in the Authorization header field of your request. The following example uses the cURL program and a sample Token for demonstration purposes.
curl -i \
-X GET \
-H "Accept: application/json" \
-H "Authorization: Token 900f05ecb028a30fa0dfa17fcf1cb17d5b5add005b"
https://api.iga.in.gov/
Important note: If you are testing or exploring the API using a Web browser, you can use a extension or add-on to configure your browser so that it includes the Authorization header in every request. One such add-on, for Mozilla Firefox, can be found here.
All resources of the MyIGA API provide application/vnd.myiga.v1+json, application/json, and text/html although some resources also provide application/pdf and application/image.
Issue an HTTP OPTIONS request to list the media types supported at the resource, for example:
curl -X OPTIONS -H "Accept: application/json" -H "Authorization: Token ..." https://api.iga.in.gov/const
Will return a description of the resource and the available mediatypes ( in the ‘renders’ property ):
{
"description": "The Indiana Constitution",
"name": "Api Constitution List",
"parses": [
"application/json"
],
"renders": [
"text/html",
"application/json",
"application/vnd.myiga.v1+json"
]
}
The consumer client can select a specific major version of the API media-type for interaction. This can be done in several ways.
MyIGA media types have the following format:
application/vnd.myiga.{MAJOR_VERSION_NUMBER}(-{SCHEMA})+{FORMAT}
All resources for API media-type version 1 currently have the following base MyIGA media-type:
application/vnd.myiga.v1+json
As an example:
curl -i \
-X GET \
-H "Accept: application/vnd.myiga.v1+json" \
-H "Authorization: Token 900f05ecb028a30fa0dfa17fcf1cb17d5b5add005b"
https://api.example.org/
Clients that are incapable of, or unwilling to use the recommended way of using the MyIGA media-type, can target a specific API version using an Accept media-type parameter named version:
{OFFICIAL_MEDIA_TYPE};version={MAJOR_VERSION_NUMBERS}
as in:
application/json;version=1
Please note: there must not be any whitespace around the semicolon.
For example, to ask for media-type version 1 of the JSON representation of the API root:
curl -i \
-X GET \
-H "Accept: application/json;version=1" \
-H "Authorization: Token 900f05ecb028a30fa0dfa17fcf1cb17d5b5add005b" \
https://api.example.org/
As a convenience, we also support the deprecated way of specifying the version of the API in the URL.
For example, to ask for media-type version 1 of the JSON representation of the Bills resource:
curl -i \
-X GET \
-H "Accept: application/json" \
-H "Authorization: Token 900f05ecb028a30fa0dfa17fcf1cb17d5b5add005b" \
https://api.example.org/v1/bills
The information provided by the MyIGA API is structured according to a common set of schema.
Resources are classified into the following types:
- Items: represents a single entity as a set of keys and values;
- Collections: represents a collection of entities as a paginated sequence of items;
- Filters: represents a subset of a collection of entities, according to its context;
Hyperlinks are presented as a (“link”, “<url>”) key-value pair. In the context of the MyIGA API, the key always “link” indicates an internal hyperlink to the resource of a separate entity.
An item is a resource that provides information about a single entity of interest.
As an example, we’d like to find out more information about the planet Jupiter, and have this information represented as JSON data.
HTTP Request:
curl -i \
-X GET \
-H "Accept: application/json" \
https://api.example.org/planets/jupiter
HTTP Response:
{
"name": "Jupiter",
"position": 5,
"distanceAU": 5.2,
"moons": 67,
"description": "Jupiter is composed largely of hydrogen and helium. Its strong internal heat creates a number of semi-permanent features in its atmosphere, such as cloud bands and the Great Red Spot.",
"link": "/planets/jupiter",
"revno": 42
}
Each item resource will have the attributes:
- link: a hyperlink that points to this resource;
- revno: the revision number of the entity represented by this resource.
A collection is a resource that represents a set of related resources.
Collections are normally paginated, and will provide useful information about themselves, including the hyperlinks of the rest of the pages.
As an example, we want to access the planets resource, to view information about the planets of our solar system.
We would also like this information to be represented as JSON data.
HTTP Request:
curl -i \
-X GET \
-H "Accept: application/json" \
https://api.example.org/planets
The server provides us with a paginated Collection resource. For now, we information and links for five of the eight known planets:
HTTP Response:
{
"itemCount": 8,
"itemsPerPage": 5,
"items": [
{
"name": "Mercury",
"position": 1,
"distanceAU": 0.4,
"moons": 0,
"description": "Mercury is the closest planet to the Sun and the smallest planet in the Solar System.",
"link": "/planets/mercury"
},
{
"name": "Venus",
"position": 2,
"distanceAU": 0.7,
"moons": 0,
"description": "Venus is close in size to Earth and, like Earth, has a thick silicate mantle around an iron core, a substantial atmosphere, and evidence of internal geological activity",
"link": "/planets/venus"
},
{
"name": "Earth",
"position": 3,
"distanceAU": 1.0,
"moons": 1,
"description": "Earth is the largest and densest of the inner planets, the only one known to have current geological activity, and the only place where life is known to exist.",
"link": "/planets/earth"
},
{
"name": "Mars",
"position": 4,
"distanceAU": 1.5,
"moons": 2,
"description": "Mars is smaller than Earth and Venus. Its surface, peppered with vast volcanoes, shows geological activity that may have persisted until as recently as 2 million years ago.",
"link": "/planets/mars"
},
{
"name": "Jupiter",
"position": 5,
"distanceAU": 5.2,
"moons": 67,
"description": "Jupiter is composed largely of hydrogen and helium. Its strong internal heat creates a number of semi-permanent features in its atmosphere, such as cloud bands and the Great Red Spot."
"link": "/planets/jupiter"
}
],
"nextLink": "/planets?page=2
}
The resource will have:
- itemCount: the total number of items in this collection
- items: the information payload
- revno: the revision number of the set of entities represented by this resource
If the resource is paginated, it may also have:
- itemsPerPage: the maximum number of items per single page (optional)
- nextLink: a link to the next subset of items in this collection (optional)
- previousLink: a link to the previous subset of items in this collection (optional)
The API client can specify a custom page size to be used in the paginated results. This is accomplished by passing the per_page parameter, as in the following example:
HTTP Request:
curl -i \
-X GET \
-H "Accept: application/json" \
https://api.example.org/planets?per_page=2
HTTP Response:
{
"itemCount": 8,
"itemsPerPage": 2,
"items": [
{
"name": "Mercury",
"position": 1,
"distanceAU": 0.4,
"moons": 0,
"description": "Mercury is the closest planet to the Sun and the smallest planet in the Solar System.",
"link": "/planets/mercury"
},
{
"name": "Venus",
"position": 2,
"distanceAU": 0.7,
"moons": 0,
"description": "Venus is close in size to Earth and, like Earth, has a thick silicate mantle around an iron core, a substantial atmosphere, and evidence of internal geological activity",
"link": "/planets/venus"
}
],
"nextLink": "/planets?per_page=2&page=2
}
The value of “per_page” can be any positive integer, but the API might enforce a maximum.
Every Collection resource can be searched using special query parameters.
In this example, we search the available information on the planets for signs of geological activity:
HTTP Request:
curl -i \
-X GET \
-H "Accept: application/json" \
https://api.example.org/planets?q=geological+activity
HTTP Response:
The response is presented to us using the same familiar layout, and also contains a reference to the parameters of the originating search request.
{
"itemCount": 4,
"items": [
{
"name": "Venus",
"position": 2,
"distanceAU": 0.7,
"moons": 0,
"description": "Venus is close in size to Earth and, like Earth, has a thick silicate mantle around an iron core, a substantial atmosphere, and evidence of internal geological activity",
"link": "/planets/venus"
},
{
"name": "Earth",
"position": 3,
"distanceAU": 1.0,
"description": "Earth is the largest and densest of the inner planets, the only one known to have current geological activity, and the only place where life is known to exist.",
"link": "/planets/earth"
},
{
"name": "Mars",
"position": 4,
"distanceAU": 1.5,
"description": "Mars is smaller than Earth and Venus. Its surface, peppered with vast volcanoes, shows geological activity that may have persisted until as recently as 2 million years ago.",
"link": "/planets/mars"
},
{
"name": "Saturn",
"position": 6,
"distanceAU": 9.5,
"description": "Saturn, distinguished by its extensive ring system, has several similarities to Jupiter, such as its atmospheric composition and magnetosphere. It has two satellites, Titan and Enceladus, that show signs of geological activity.",
"link": "/planets/mars"
}
],
"parameters": {
"q": "geological activity"
}
}
The format of identifiers on api.iga.in.gov, with the exception of bill names and bill versions should be treated as arbitrary and subject to change.
Bill / resolution versions however have a fixed parsable format, shown below:
{bill type}{bill number}.{bill stage}.{bill print version}
The bill type can be one of:
| Bill Type | Description |
|---|---|
| SB | Senate Bill |
| SC | Senate Concurrent Resolution |
| SJ | Senate Joint Resolution |
| SR | Senate Resolution |
| HB | House Bill |
| HC | House Concurrent Resolution |
| HJ | House Joint Resolution |
| HR | House Resolution |
Bill number is a 4 digit number starting from 0 for resolutions and from 1000 for bills.
Bill stage can be one of:
| Bill Stage | Description |
|---|---|
| INTR | Introduced Bill |
| COMH | House Bill |
| COMS | Senate Bill |
| ENGH | Engrossed House Bill |
| ENGS | Engrossed Senate Bill |
| ENRH | Enrolled House Bill |
| ENRS | Enrolled Senate Bill |
Bill print version is a two digit number starting at 01. The print version caters for situations in which a bill needs to be ‘re-printed’, usually in response to a drafting error.