Using the MYIGA Hypermedia API

Introduction

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.

Authentication and authorization

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.

Media Types

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"
    ]
}

API versions

The consumer client can select a specific major version of the API media-type for interaction. This can be done in several ways.

Using the official Internet media-types

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/

Using the version number in the URL (deprecated)

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 MyIGA Hypermedia Language

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.

Items

An item is a resource that provides information about a single entity of interest.

Viewing an Item

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.

Collections

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.

Viewing a Collection

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)

Specify a page size for a paginated Collection

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.

Searching a Collection

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"
    }
}

Filters

Filters are collections that represent a subset of the related entities represented by another collection. All the properties of canonical collections apply to them.

Content provided by Wikipedia.

Unique Identifiers

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.