apiary.apib

FORMAT: 1A
HOST: https://data.detroitledger.org/api/1.0

# detroitledger

The [Detroit Ledger](http://www.detroitledger.org) is a dataset of grants made in Detroit. Use this API to programatically access information about grants and organizations.

# Notes

## Ledger Universe IDs

Our system will associate an ID with each grant and organization - these IDs will stay the same during a session (i.e. you ask for orgs, query org/someid, then query org/anotherid, and query org/someid again)... but they may change eventually. Don't rely on them; instead run a search based on a global identifier like an EIN.

TODO: how exactly do our UUIDs work / what causes them to change?

## Response formats

The default response format is XML. Other formats include bencode, json, jsonp, and serialized PHP (php). The format is selected by appending the format code to the URL, followed by a slash. For example, add ".json" as a suffix to receive JSON data.

JSONP callback can be specified with a callback argument: `http://data.detroitledger.org/api/1.0/orgs.jsonp?limit=1&offset=2&filters[org_grants_received]=22220:99999&callback=cb`

## Boilerplate

Single entities will contain the following content management- revision-related properties:

    "log": "fixed typo" // last revision's editing note
    "name": "Basil Frankenweiler" // creator's username
    "path": "http://data.detroitledger.org/permalink/forthis/thing", // html representation URI 4 humans
    "revision_timestamp": "1381515552", // unix timestamp
    "revision_uid": "0", // who authored last revision?
    "type": "org", // entity type
    "uid": "0", // user id who created this item (0 means it was imported)
    "uuid": "6a62087a-c996-4e3b-bfbb-d2dd28d6f429", // unique id
    "vid": "22033", // revision id
    "vuuid": "7b3a962a-a2cb-49d4-abce-8fd61ae23ecb" // revision unique id
    "changed": "1381515552", // unix timestamp of date last changed
    "created": "1381515552", // unix timestamp of date created

# Group Organization
## Organization [/orgs/:id]

+ Parameters

    + id (number, required, `12345`) ... Organization ID.

+ Model (application/json)

    + Body

            {
            "body": null,
            "changed": "1390276370",
            "comment": "0",
            "created": "1390276370",
            "field_ein": null,
            "field_ntee": {
                "tid": "591"
            },
            "field_org_address": {
                "administrative_area": "MI",
                "country": "US",
                "data": null,
                "dependent_locality": null,
                "first_name": null,
                "last_name": null,
                "locality": "Detroit",
                "name_line": null,
                "organisation_name": null,
                "postal_code": "",
                "premise": "",
                "sub_administrative_area": null,
                "sub_premise": null,
                "thoroughfare": ""
            },
            "field_org_lifespan": null,
            "field_org_links": null,
            "field_org_tags": null,
            "field_state_corp_id": null,
            "id": "592",
            "log": "",
            "name": "",
            "org_grants_datestart": 2011,
            "org_grants_funded": 2552025,
            "org_grants_received": 0,
            "revision_timestamp": "1390276370",
            "revision_uid": "0",
            "status": "1",
            "title": "Carls Foundation",
            "tnid": "0",
            "translate": "0",
            "type": "org",
            "uid": "0",
            "uuid": "1bc3e07b-b0c4-4a0c-869c-5e883f3861fa",
            "vid": "592",
            "vuuid": "91070591-de16-48b8-a293-2f73735ab100"
            }


### Retrieve a single Organization [GET]
+ Response 200 (application/json)

    [Organization][]

## Grants Funded by Organization [/orgs/:id/grants_funded{?limit,offset}]
### Lists grants funded by a speific organization [GET]
+ Parameters

    + id (number, required, `12345`) ... Organization ID.
    + limit = `10` (number, optional) ... Limit response set to this many
    + offset = `0` (number, optional) ... Begin results at this index

+ Response 200 (application/json)
        {
          "grants_funded": [
            {
              [Grant][]
            },
            {
              // ... more grants
            }
          ]
        }

## Grants Received by Organization [/orgs/:id/grants_received{?limit,offset}]
### Lists grants received by a speific organization [GET]
+ Parameters

    + id (number, required, `12345`) ... Organization ID.
    + limit = `10` (number, optional) ... Limit response set to this many
    + offset = `0` (number, optional) ... Begin results at this index

+ Response 200 (application/json)
        {
          "grants_received": [
            {
              [Grant][]
            },
            {
              // ... more grants
            }
          ]
        }

## Board Members of an Organization [/orgs/:id/board_members{?limit,offset}]
### Lists board members of a specific organiztaion

`person_id` refers to a [Person][].

+ Parameters

    + id (number, required, `12345`) ... Organization ID.
    + limit = `10` (number, optional) ... Limit response set to this many
    + offset = `0` (number, optional) ... Begin results at this index

+ Response 200 (application/json)
        {
          "board_members": [
            {
              "compensation": null,
              "name": "Allan D. Gilmour",
              "person_id": "4797",
              "position": "Chair",
              "term_end": "2012-12-31 00:00:00",
              "term_start": "2012-01-01 00:00:00"
            },
            {
              // ... more board members
            }
          ]
        }


## Organizations Index [/orgs{?limit,offset,filters,sort}]
### List all Organizations [GET]
+ Parameters

    + limit = `10` (number, optional) ... Limit response set to this many
    + offset = `0` (number, optional) ... Begin results at this index
    + filters (array, optional) ... Filter fields (e.g. `filters[title]=etroit`, `filters[org_grants_funded]=2000:100000`, `filters[tid]=154', or `filters[org_grants_received]=100:2000`
    + sort (array, optional) ... Add a sort to the query (uses query aliases, e.g. `sort[n.title]=ASC`). Only the first sort option is used. For ordering by total grants funded or received, use sort keys `funded` or `received`.

+ Response 200 (application/json)

        {
          "orgs": [
            {
              [Organization][]
            },
            {
              // ... more organizations
            }
          ]
        }

# Group Grant
## Grant [/grants/:id]
+ Parameters

    + id (number, required, `12345`) ... Grant ID.

+ Model (application/json)

    + Body

        {
            "body": null,
            "changed": "1390276395",
            "comment": "0",
            "field_end_date": "Tue, 01 Jan 2013 05:00:00 -0500",
            "created": "1390276395",
            "field_funded_amount": {
                "value": "750000"
            },
            "field_funder": {
                "name": "Carls Foundation",
                "target_id": "592"
            },
            "field_grant_tags": null,
            "field_grant_types": null,
            "field_internal_notes": "{\"impact_area\":\"Detroit\"}",
            "field_recipient": {
                "name": "Forgotten Harvest, Inc",
                "target_id": "226"
            },
            "field_source": "IRS 990 2011",
            "field_start_date": "Sun, 01 Jan 2012 05:00:00 -0500",
            "field_year": {
                "date_type": "datetime",
                "timezone": "America/Detroit",
                "timezone_db": "America/Detroit",
                "value": "2011-01-01 05:00:00",
                "value2": "2012-01-01 05:00:00"
            },
            "id": "1821",
            "log": "",
            "name": "",
            "notes": "<p>safe html-formatted notes about the grant</p>",
            "revision_timestamp": "1390276395",
            "revision_uid": "0",
            "status": "1",
            "title": "Carls Foundation -> Forgotten Harvest, Inc",
            "tnid": "0",
            "translate": "0",
            "type": "grant",
            "uid": "0",
            "uuid": "d0fd3190-8b99-44ab-92fc-c678ca9cd1fb",
            "vid": "1821",
            "vuuid": "09d53741-a264-496c-9d3f-56c4a3cb83cf"
        }

### Retrieve a single Grant [GET]
+ Response 200 (application/json)

    [Grant][]

## Grants Index [/grants{?limit,offset,filters,sort}]
### List all Grants [GET]
+ Parameters

    + limit = `10` (number, optional) ... Limit response set to this many
    + offset = `0` (number, optional) ... Begin results at this index
    + filters (array, optional) ... Filter fields (e.g. `filters[title]=gift`)
    + sort (array, optional) ... Add a sort to the query (uses query aliases, e.g. `sort[n.title]=ASC`). Only the first sort option is used.

+ Response 200 (application/json)

        {
          "grants": [
            {
              [Grant][]
            },
            {
              // ... more grants
            }
          ]
        }

# Group NTEE
## NTEE [/ntees/:id]
+ Parameters

    + id (number, required, `12345`) ... NTEE ID (ledger-specific, not the actual code).

+ Model (application/json)

    + Body

        {
            "depth": 0,
            "description": null,
            "field_ntee_code": {
                "und": [
                    {
                        "format": null,
                        "safe_value": "K",
                        "value": "K"
                    }
                ]
            },
            "format": "plain_text",
            "id": "276",
            "name": "Agriculture, Food, Nutrition",
            "org_ids": [
                "3420",
                "133"
            ],
            "orgs": [
                [
                   [Org][]
                ]
            ],
            "parents": [
                "0"
            ],
            "tid": "276",
            "type": "ntees",
            "uuid": "62dd848d-48c5-4eeb-aa72-8589d6ca9e42",
            "vid": "3",
            "vocabulary_machine_name": "ntee",
            "weight": "0"
        },


## NTEE Index [/ntees{?load_orgs}]
### List all Organization NTEE Codes [GET]
+ Parameters

    + load_orgs = `false` (boolean, optional) ... Load organization entities?

+ Response 200 (application/json)

        {
          "data": [
            {
              [NTEE][]
            },
            {
              // ... more NTEE objects
            }
          ],
          "meta": {
            "total": 643
          }
        }


# GET /stats
+ Response 200 (application/json)

      {
          "total_num_grants": 1,
          "total_num_orgs": 1,
          "total_num_funders": 1,
          "total_num_recipients": 1,
          "total_grants_dollars": 1
      }

# Group Flag
## Flag [/flags/:id]
+ Parameters

    + id (number, required, `12345`) ... Flag ID.

+ Model (application/json)

    + Body

        {
            "flag": {
                "id": 9999,
                "target_id": 1821, // entity id of grant or organization
                "note": "This is a duplicate of grant id 1822"
            }
        }

### Retrieve a single Flag [GET]
+ Response 200 (application/json)

    [Flag][]

## Create Flag [/flags/]
### Flag a Grant or Organization [POST]
+ Request

    + Headers

        Content-Type: application/json
        Accept: application/json

    + Body

        {
            "flag": {
                "target_id": 1821,
                "note": "This is a duplicate of grant id 1822"
            }
        }

+ Response 201

    + Body

        [Flag][]

+ Response 400

    + Body

        entity id 1821 does not exist.