Docs

Quick Links

Overview
- Anatomy of a Basic Request
- Defaults
API Metadata (Root Node)
Legislation
Meetings
- Get a list of all meetings
- Get a single meeting

Overview

This page contains the overview for the Surveys API. It will discuss topics such as the anatomy of a basic request, defaults and custom headers used for versioning and specifying MIME type, and how to use the documentation.

Anatomy of a Basic Request

Here is an example of a basic request that you might compose to get survey data.

$ curl -X GET -H 'Accept: application/vnd.troycitycouncil.v1+json' \
  http://legislative-twitter.herokuapp.com/api/legislations?type=Resolution

In this case, we’re getting all the legislation of the Resolution type. Let’s break down this request piece by piece.

cURL

curl is a tool used to transfer data over a URL. It is widely used (with over a billion users, according to the website) and is usually considered the standard. In this case, we’re using curl to retrieve Survey API’s JSON response. For more information about how to use curl, read the docs.

-X <command>

The -X <command> (or --request <command>) tag designates what kind of CRUD request you are making: GET, POST, PATCH, PUT, or DELETE. The default is GET, so if all you are doing is retrieving information, this can be left off.

-d <data>

This is the data that we’re sending to the Survey application. The -d <data> (or --data <data>) tag sends data to the url. We didn’t use this option in the example command, but you will use it with any PUT or PATCH request.

-H <header>

The -H <header> (or --header <header>) tag sends extra headers to the server. In this case, we’re sending the Accept header of application/vnd.troycitycouncil.v1+json. This is a custom accept header used by Surveys API to explicitly denote the API version (v1) and the response MIME type (JSON). We strongly recommend to always explicitly include this Accept header in any app using our data; it will ensure that any future breaking changes to our API do not affect your application.

Endpoints

The URL at the end of the curl command corresponds to the API endpoint–keeping with the spirit of a RESTful API, each resource has a unique endpoint. The endpoints for different actions are the first item listed in the documentation for each possible action below (ex. GET /api/meetings).

To get all of a type of resources or to create a new resource, go to https://.../api/meetings. To get details of a specific resource, to update a resource, or to delete a resource, include the resource id in the url: http://.../api/meetings/3. To add parameters (where allowed–see documentation), prefix it with a ? like so: http://.../surveys?name=Survey.

Defaults

Surveys sets some defaults for the ease of testing and trying out our API. We strongly recommend that in your application, you declare these settings explicitly.

MIME Type: JSON

All responses have a MIME-type of JSON.

Version: v1

All calls default to version 1 of our API in order to allow developers to explore from the browser. However, we strongly recommend that you set this explicitly in your code with the following Accept header:

application/vnd.surveys.v1+json

If we every add breaking changes and go up API versions, the new default will be the current version of the API. If your application does not explicitly declare an API version, it will stop working.

Documentation Format

In the following sections, we’ll explore the different ways you can interact with the Surveys API. Each category (“Meetings”) contains sections (“Get a list of all meetings”) that correspond to each type of possible request. Each section contains:

the REST verb and request URI
an example curl request
the response headers and body

Please feel free to copy and paste the example request into your terminal to see how it works!

Quick Links

Overview
- Anatomy of a Basic Request
- Defaults
API Metadata (Root Node)
Legislation
Meetings
- Get a list of all meetings
- Get a single meeting

API Metadata (Root Node)

GET /api

View this endpoint in the browser

The API root url contains metadata for the Legislative Twitter APIs. This metadata includes:

API version number
links to each contained API

Example Request

$ curl -i -H 'Accept: application/vnd.troycitycouncil.v1+json' \
  https://legislative-twitter-dev.herokuapp.com/api

Response

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Status: 200 OK
Cache-Control: max-age=0, private, must-revalidate
Etag: W/"ac7c4fa05a2a3d0df719d07938ebc25e"
X-Frame-Options: SAMEORIGIN
X-Xss-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Runtime: 0.005214
X-Request-Id: d729d5bf-91ea-4e7f-be78-1ffec7142db7
Date: Fri, 10 Apr 2015 08:49:05 GMT
X-Powered-By: Phusion Passenger 5.0.4
Server: nginx/1.6.2 + Phusion Passenger 5.0.4
Via: 1.1 vegur

{
  "api_version": "v1",
  "legislations": "https://legislative-twitter-dev.herokuapp.com/api/legislations",
  "meetings": "https://legislative-twitter-dev.herokuapp.com/api/meetings"
}

Quick Links

Overview
- Anatomy of a Basic Request
- Defaults
API Metadata (Root Node)
Legislation
Meetings
- Get a list of all meetings
- Get a single meeting

Legislation

This section contains each action that can be performed on surveys via the Legislation API including an example script and request as well as the associated endpoint.

Get a list of all legislation

GET /api/legislations

View this endpoint in the browser

Example Request

$ curl -i -H 'Accept: application/vnd.troycitycouncil.v1+json' \
  https://legislative-twitter-dev.herokuapp.com/api/legislations

Response

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Status: 200 OK
Cache-Control: max-age=0, private, must-revalidate
Etag: W/"83154f7133646fd36de8a579b45dd577"
X-Frame-Options: SAMEORIGIN
X-Xss-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Runtime: 0.021816
X-Request-Id: 6b07c438-b176-4e1f-8b13-b24cc80136a8
Date: Fri, 10 Apr 2015 08:55:09 GMT
X-Powered-By: Phusion Passenger 5.0.4
Server: nginx/1.6.2 + Phusion Passenger 5.0.4
Via: 1.1 vegur

[
  {
    "id": 1,
    "legislation_type": "Ordinance",
    "title": "Ordinance Amending Ordinance No. 12 Adopted by the Troy City Council on December 4, 1975; as Amended by Ordinance No.1 Adopted December 15, 1979; as Amended by Ordinance No.1 Adopted December 1, 1981; as Amended by Ordinance No.1 Adopted Aprill4, 1983; as Amended by Ordinance No.1 Adopted April2, 1992; as Amended by Ordinance No.2 Adopted January 19, 1996; as Amended by Ordinance No.3 Adopted January 8, 1998; as Amended by Ordinance No. 15 Adopted December 7, 2000; as Amended by Ordinance No. 1 Adopted November 30, 2006; as Amended by Ordinance No. 3 Adopted November 20, 2012; Which Pursuant to Section 10.06 ofthe City Charter and Section 30-17 ofthe Troy Code o f Ordinances Established a Code o f Rules and Regulations for the Department o f Public Utilities and as Amended to fucrease the Sewer Rate From 65% to 85% ofthe Water Bill Rate. (Council President Wiltshire) (At the Request ofthe Administration)",
    "short_title": "Increase Sewer Rate",
    "body": "Neque purus pede condimentum pretium sollicitudin. Lacus morbi non vestibulum habitasse ante aliquet ad. Ipsum felis aptent aenean quisque et quam. Etiam felis ipsum auctor metus. Magna porta eleifend adipiscing.",
    "url": "https://legislative-twitter-dev.herokuapp.com/api/legislations/1"
  },
  {
    "id": 3,
    "legislation_type": "Ordinance",
    "title": "Ordinance Approving Settlement ofTax Certiorari Proceedings fustituted by Bryce Properties LLC on the Assessment Roll ofthe City ofTroy. (Council President Wiltshire) (At the Request ofthe Administration)",
    "short_title": "Tax Certiorari Proceedings of Bryce Properties",
    "body": "Neque purus pede condimentum pretium sollicitudin. Lacus morbi non vestibulum habitasse ante aliquet ad. Ipsum felis aptent aenean quisque et quam. Etiam felis ipsum auctor metus. Magna porta eleifend adipiscing.",
    "url": "https://legislative-twitter-dev.herokuapp.com/api/legislations/3"
  },
  ...
]

Get a list of legislation by type

GET /api/legislations?type=Ordinance

View this endpoint in the browser (change the value of type to return different surveys).

Valid Types

Valid legislation types are Resolution and Ordinance.

Example Request

$ curl -i -H 'Accept: application/vnd.troycitycouncil.v1+json' \
  https://legislative-twitter-dev.herokuapp.com/api/legislations?type=Ordinance

Response

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Status: 200 OK
Cache-Control: max-age=0, private, must-revalidate
Etag: W/"a22e9b5e6dade5c4d810682218147aa2"
X-Frame-Options: SAMEORIGIN
X-Xss-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Runtime: 0.008117
X-Request-Id: c31d84a8-41ec-4e37-81dc-d68c1b314456
Date: Fri, 10 Apr 2015 09:01:37 GMT
X-Powered-By: Phusion Passenger 5.0.4
Server: nginx/1.6.2 + Phusion Passenger 5.0.4
Via: 1.1 vegur

[
  {
    "id": 1,
    "legislation_type": "Ordinance",
    "title": "Ordinance Amending Ordinance No. 12 Adopted by the Troy City Council on December 4, 1975; as Amended by Ordinance No.1 Adopted December 15, 1979; as Amended by Ordinance No.1 Adopted December 1, 1981; as Amended by Ordinance No.1 Adopted Aprill4, 1983; as Amended by Ordinance No.1 Adopted April2, 1992; as Amended by Ordinance No.2 Adopted January 19, 1996; as Amended by Ordinance No.3 Adopted January 8, 1998; as Amended by Ordinance No. 15 Adopted December 7, 2000; as Amended by Ordinance No. 1 Adopted November 30, 2006; as Amended by Ordinance No. 3 Adopted November 20, 2012; Which Pursuant to Section 10.06 ofthe City Charter and Section 30-17 ofthe Troy Code o f Ordinances Established a Code o f Rules and Regulations for the Department o f Public Utilities and as Amended to fucrease the Sewer Rate From 65% to 85% ofthe Water Bill Rate. (Council President Wiltshire) (At the Request ofthe Administration)",
    "short_title": "Increase Sewer Rate",
    "body": "Neque purus pede condimentum pretium sollicitudin. Lacus morbi non vestibulum habitasse ante aliquet ad. Ipsum felis aptent aenean quisque et quam. Etiam felis ipsum auctor metus. Magna porta eleifend adipiscing.",
    "url": "https://legislative-twitter-dev.herokuapp.com/api/legislations/1"
  },
  {
    "id": 3,
    "legislation_type": "Ordinance",
    "title": "Ordinance Approving Settlement ofTax Certiorari Proceedings fustituted by Bryce Properties LLC on the Assessment Roll ofthe City ofTroy. (Council President Wiltshire) (At the Request ofthe Administration)",
    "short_title": "Tax Certiorari Proceedings of Bryce Properties",
    "body": "Neque purus pede condimentum pretium sollicitudin. Lacus morbi non vestibulum habitasse ante aliquet ad. Ipsum felis aptent aenean quisque et quam. Etiam felis ipsum auctor metus. Magna porta eleifend adipiscing.",
    "url": "https://legislative-twitter-dev.herokuapp.com/api/legislations/3"
  },
  ...
]

Get a single legislation

GET /api/legislations/3

View this endpoint in the browser

Example Request

$ curl -i -H 'Accept: application/vnd.troycitycouncil.v1+json' \
  https://legislative-twitter-dev.herokuapp.com/api/legislations/3

Response

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Status: 200 OK
Cache-Control: max-age=0, private, must-revalidate
Etag: W/"e6076c520efe05cd26fb30b517bd9c0e"
X-Frame-Options: SAMEORIGIN
X-Xss-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Runtime: 0.007213
X-Request-Id: 070bc9d8-4fb0-47f0-89b6-4e0b9dc57b2c
Date: Fri, 10 Apr 2015 09:06:31 GMT
X-Powered-By: Phusion Passenger 5.0.4
Server: nginx/1.6.2 + Phusion Passenger 5.0.4
Via: 1.1 vegur

{
  "id": 3,
  "legislation_type": "Ordinance",
  "title": "Ordinance Approving Settlement ofTax Certiorari Proceedings fustituted by Bryce Properties LLC on the Assessment Roll ofthe City ofTroy. (Council President Wiltshire) (At the Request ofthe Administration)",
  "short_title": "Tax Certiorari Proceedings of Bryce Properties",
  "body": "Neque purus pede condimentum pretium sollicitudin. Lacus morbi non vestibulum habitasse ante aliquet ad. Ipsum felis aptent aenean quisque et quam. Etiam felis ipsum auctor metus. Magna porta eleifend adipiscing.",
  "created_at": "2015-03-21 17:57:48 -0400",
  "updated_at": "2015-03-21 17:57:48 -0400"
}

Quick Links

Overview
- Anatomy of a Basic Request
- Defaults
API Metadata (Root Node)
Legislation
Meetings
- Get a list of all meetings
- Get a single meeting

Meetings

This section contains each action that can be performed on surveys via the Meetings API including an example script and request as well as the associated endpoint.

Get a list of all meetings

GET /api/meetings

View this endpoint in the browser

Example Request

$ curl -i -H 'Accept: application/vnd.troycitycouncil.v1+json' \
  https://legislative-twitter-dev.herokuapp.com/api/meetings

Response

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Status: 200 OK
Cache-Control: max-age=0, private, must-revalidate
Etag: W/"058198503425495b4e67e99db1ae475d"
X-Frame-Options: SAMEORIGIN
X-Xss-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Runtime: 0.027177
X-Request-Id: db70f657-d4a6-46b2-8d9f-4c407fe6863c
Date: Fri, 10 Apr 2015 15:28:41 GMT
X-Powered-By: Phusion Passenger 5.0.4
Server: nginx/1.6.2 + Phusion Passenger 5.0.4
Via: 1.1 vegur

[
  {
    "id": 2,
    "name": "Finance Committee Meeting on March 23rd, 2015 12:00",
    "date": "2015-03-23 12:00:00 -0400",
    "location": "Suite 5, 433 River Street, Troy, NY 12180",
    "legislation_count": 5,
    "organization": {
      "id": 3,
      "name": "Finance Committee",
      "url": "https://legislative-twitter-dev.herokuapp.com/organizations/3.json"
    },
    "agenda": "https://legislative-twitter-dev.herokuapp.com/meetings/2/agenda.json",
    "minutes": "https://legislative-twitter-dev.herokuapp.com/meetings/2/minutes.json",
    "url": "https://legislative-twitter-dev.herokuapp.com/api/meetings/2"
  },
  {
    "id": 1,
    "name": "Finance Committee Meeting on December 18th, 2014 19:00",
    "date": "2014-12-18 19:00:00 -0500",
    "location": "Suite 5, 433 River Street, Troy, NY 12180",
    "legislation_count": 14,
    "organization": {
      "id": 3,
      "name": "Finance Committee",
      "url": "https://legislative-twitter-dev.herokuapp.com/organizations/3.json"
    },
    "agenda": "https://legislative-twitter-dev.herokuapp.com/meetings/1/agenda.json",
    "minutes": "https://legislative-twitter-dev.herokuapp.com/meetings/1/minutes.json",
    "url": "https://legislative-twitter-dev.herokuapp.com/api/meetings/1"
  },
  ...
]

Get a single meeting

GET /api/meetings/3

View this endpoint in the browser

Example Request

$ curl -i -H 'Accept: application/vnd.troycitycouncil.v1+json' \
  https://legislative-twitter-dev.herokuapp.com/api/meetings/3

Response

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Status: 200 OK
Cache-Control: max-age=0, private, must-revalidate
Etag: W/"26896ff16d917ce3f6fdd00db2ceb0e8"
X-Frame-Options: SAMEORIGIN
X-Xss-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Runtime: 0.072665
X-Request-Id: 3f91dcee-461a-46c7-893f-7ce9810fc7fd
Date: Fri, 10 Apr 2015 15:30:05 GMT
X-Powered-By: Phusion Passenger 5.0.4
Server: nginx/1.6.2 + Phusion Passenger 5.0.4
Via: 1.1 vegur

{
  "id": 3,
  "name": "City Council Meeting on March 30th, 2015 21:00",
  "date": "2015-03-30 21:00:00 -0400",
  "location": "Suite 5, 433 River Street, Troy, NY 12180",
  "created_at": "2015-03-21 19:52:59 -0400",
  "updated_at": "2015-03-25 20:29:39 -0400",
  "legislation_count": 6,
  "organization": {
    "id": 2,
    "name": "City Council",
    "url": "https://legislative-twitter-dev.herokuapp.com/organizations/2.json"
  },
  "agenda": {
    "approved": false,
    "url": "https://legislative-twitter-dev.herokuapp.com/meetings/3/agenda.json"
  },
  "minutes": {
    "approved": false,
    "url": "https://legislative-twitter-dev.herokuapp.com/meetings/3/minutes.json"
  },
  "legislations": [
    {
      "id": 4,
      "title": "Ordinance Amending the 2015 City Budget to Transfer Funds Within the General and Water Fund Budget Lines. (Council President Wiltshire) (At the Request ofthe Administration)",
      "short_title": "Transfer Funds within Water Fund Budget",
      "sponsor": null,
      "url": "https://legislative-twitter-dev.herokuapp.com/api/legislations/4"
    },
    {
      "id": 3,
      "title": "Ordinance Approving Settlement ofTax Certiorari Proceedings fustituted by Bryce Properties LLC on the Assessment Roll ofthe City ofTroy. (Council President Wiltshire) (At the Request ofthe Administration)",
      "short_title": "Tax Certiorari Proceedings of Bryce Properties",
      "sponsor": null,
      "url": "https://legislative-twitter-dev.herokuapp.com/api/legislations/3"
    },
    ...
  ]
}

Quick Links

Overview
- Anatomy of a Basic Request
- Defaults
API Metadata (Root Node)
Legislation
Meetings
- Get a list of all meetings
- Get a single meeting