Open311 API Spec

<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <base target="_top"> <style type="text/css"> /* default css */ table { font-size: 1em; line-height: inherit; border-collapse: collapse; } tr { text-align: left; } div, address, ol, ul, li, option, select { margin-top: 0px; margin-bottom: 0px; } p { margin: 0px; } pre { font-family: Courier New; white-space: pre-wrap; margin:0; } body { margin: 6px; padding: 0px; font-family: Verdana, sans-serif; font-size: 10pt; background-color: #ffffff; } img { -moz-force-broken-image-icon: 1; } @media screen { html.pageview { background-color: #f3f3f3 !important; } body { min-height: 1100px; counter-reset: __goog_page__; } * html body { height: 1100px; } .pageview body { border-top: 1px solid #ccc; border-left: 1px solid #ccc; border-right: 2px solid #bbb; border-bottom: 2px solid #bbb; width: 648px !important; margin: 15px auto 25px; padding: 40px 50px; } /* IE6 */ * html { overflow-y: scroll; } * html.pageview body { overflow-x: auto; } /* Prevent repaint errors when scrolling in Safari. This "Star-7" css hack targets Safari 3.1, but not WebKit nightlies and presumably Safari 4. That's OK because this bug is fixed in WebKit nightlies/Safari 4 :-). */ html*#wys_frame::before { content: '\A0'; position: fixed; overflow: hidden; width: 0; height: 0; top: 0; left: 0; } .writely-callout-data { display: none; *display: inline-block; *width: 0; *height: 0; *overflow: hidden; } .writely-footnote-marker { background-image: url('MISSING'); background-color: transparent; background-repeat: no-repeat; width: 7px; overflow: hidden; height: 16px; vertical-align: top; -moz-user-select: none; } .editor .writely-footnote-marker { cursor: move; } .writely-footnote-marker-highlight { background-position: -15px 0; -moz-user-select: text; } .writely-footnote-hide-selection ::-moz-selection, .writely-footnote-hide-selection::-moz-selection { background: transparent; } .writely-footnote-hide-selection ::selection, .writely-footnote-hide-selection::selection { background: transparent; } .writely-footnote-hide-selection { cursor: move; } .editor .writely-comment-yellow { background-color: #FF9; background-position: -240px 0; } .editor .writely-comment-yellow-hover { background-color: #FF0; background-position: -224px 0; } .editor .writely-comment-blue { background-color: #C0D3FF; background-position: -16px 0; } .editor .writely-comment-blue-hover { background-color: #6292FE; background-position: 0 0; } .editor .writely-comment-orange { background-color: #FFDEAD; background-position: -80px 0; } .editor .writely-comment-orange-hover { background-color: #F90; background-position: -64px 0; } .editor .writely-comment-green { background-color: #99FBB3; background-position: -48px 0; } .editor .writely-comment-green-hover { background-color: #00F442; background-position: -32px 0; } .editor .writely-comment-cyan { background-color: #CFF; background-position: -208px 0; } .editor .writely-comment-cyan-hover { background-color: #0FF; background-position: -192px 0; } .editor .writely-comment-purple { background-color: #EBCCFF; background-position: -144px 0; } .editor .writely-comment-purple-hover { background-color: #90F; background-position: -128px 0; } .editor .writely-comment-magenta { background-color: #FCF; background-position: -112px 0; } .editor .writely-comment-magenta-hover { background-color: #F0F; background-position: -96px 0; } .editor .writely-comment-red { background-color: #FFCACA; background-position: -176px 0; } .editor .writely-comment-red-hover { background-color: #FF7A7A; background-position: -160px 0; } .editor .writely-comment-marker { background-image: url('MISSING'); background-color: transparent; padding-right: 11px; background-repeat: no-repeat; width: 16px; height: 16px; -moz-user-select: none; } .editor .writely-comment-hidden { padding: 0; background: none; } .editor .writely-comment-marker-hidden { background: none; padding: 0; width: 0; } .editor .writely-comment-none { opacity: .2; filter:progid:DXImageTransform.Microsoft.Alpha(opacity=20); -moz-opacity: .2; } .editor .writely-comment-none-hover { opacity: .2; filter:progid:DXImageTransform.Microsoft.Alpha(opacity=20); -moz-opacity: .2; } .br_fix br:not(:-moz-last-node):not(:-moz-first-node) { position:relative; left: -1ex } .br_fix br+br { position: static !important } #cb-p-tgt { font-size: 8pt; padding: .4em; font-style: oblique; background-color: #FFF1A8; border: 1px solid #000; } } h6 { font-size: 8pt } h5 { font-size: 8pt } h4 { font-size: 10pt } h3 { font-size: 12pt } h2 { font-size: 14pt } h1 { font-size: 18pt } blockquote {padding: 10px; border: 1px #DDD dashed } .webkit-indent-blockquote { border: none; } a img {border: 0} .pb { border-width: 0; page-break-after: always; /* We don't want this to be resizeable, so enforce a width and height using !important */ height: 1px !important; width: 100% !important; } .editor .pb { border-top: 1px dashed #C0C0C0; border-bottom: 1px dashed #C0C0C0; } div.google_header, div.google_footer { position: relative; margin-top: 1em; margin-bottom: 1em; } /* Table of contents */ .editor div.writely-toc { background-color: #f3f3f3; border: 1px solid #ccc; } .writely-toc > ol { padding-left: 3em; font-weight: bold; } ol.writely-toc-subheading { padding-left: 1em; font-weight: normal; } /* IE6 only */ * html writely-toc ol { list-style-position: inside; } .writely-toc-none { list-style-type: none; } .writely-toc-decimal { list-style-type: decimal; } .writely-toc-upper-alpha { list-style-type: upper-alpha; } .writely-toc-lower-alpha { list-style-type: lower-alpha; } .writely-toc-upper-roman { list-style-type: upper-roman; } .writely-toc-lower-roman { list-style-type: lower-roman; } .writely-toc-disc { list-style-type: disc; } /* Ordered lists converted to numbered lists can preserve ordered types, and vice versa. This is confusing, so disallow it */ ul[type="i"], ul[type="I"], ul[type="1"], ul[type="a"], ul[type="A"] { list-style-type: disc; } ol[type="disc"], ol[type="circle"], ol[type="square"] { list-style-type: decimal; } /* end default css */ /* default print css */ @media print { body { padding: 0; margin: 0; } div.google_header, div.google_footer { display: block; min-height: 0; border: none; } div.google_header { flow: static(header); } /* used to insert page numbers */ div.google_header::before, div.google_footer::before { position: absolute; top: 0; } div.google_footer { flow: static(footer); } /* always consider this element at the start of the doc */ div#google_footer { flow: static(footer, start); } span.google_pagenumber { content: counter(page); } span.google_pagecount { content: counter(pages); } callout.google_footnote { display: prince-footnote; footnote-style-position: inside; /* These styles keep the footnote from taking on the style of the text surrounding the footnote marker. They can be overridden in the document CSS. */ color: #000; font-family: Verdana; font-size: 10.0pt; font-weight: normal; } /* Table of contents */ #WritelyTableOfContents a::after { content: leader('.') target-counter(attr(href), page); } #WritelyTableOfContents a { text-decoration: none; color: black; } } @page { @top { content: flow(header); } @bottom { content: flow(footer); } @footnotes { border-top: solid black thin; padding-top: 8pt; } } /* end default print css */ /* custom css */ /* end custom css */ /* ui edited css */ body { font-family: Verdana; font-size: 10.0pt; line-height: normal; background-color: #ffffff; } /* end ui edited css */ /* editor CSS */ .editor a:visited {color: #551A8B} .editor table.zeroBorder {border: 1px dotted gray} .editor table.zeroBorder td {border: 1px dotted gray} .editor table.zeroBorder th {border: 1px dotted gray} .editor div.google_header, .editor div.google_footer { border: 2px #DDDDDD dashed; position: static; width: 100%; min-height: 2em; } .editor .misspell {background-color: yellow} .editor .writely-comment { font-size: 9pt; line-height: 1.4; padding: 1px; border: 1px dashed #C0C0C0 } /* end editor CSS */ </style> <title>Open311 API Spec v0.1-2009-16-18</title> </head> <body > <div style=TEXT-ALIGN:center> Open311 API Draft Specification 2009-06 v0.1 </div> Abstract The Open311 API provides a way to work with service requests between citizens, governments and non-governmental organizations. Open311 is decentralized. There is no central registry to which a providing system is required to register. There is also no central authority that lists the responsible Open311 providers for a particular location or set of concerns. Open311 is intended to be applicable every where for all languages. The spec has been initially written in English with English terms solely for the convenience of the authors. All attempts were made to provide for the API to work for all language locales. Open311 uses only standard HTTP requests and responses. The Open311 API is a RESTful service. All GET requests are idempotent, they have no side effect other then returning data in a response to the client. It is expected that multiple versions of the Open311 API will exist and interoperate concurrently. The spec is designed to allow service providers of different versions to be able to communicate together. Terminology Provider or Service Provider The system on which the API calls are made. This is the system that is mapped to by the URIs that a client makes HTTP calls to. Client The entity or system from which API calls are made. This could be a citizen's browser, a third party computer system or another service provider. Issue A specific, geographically stationary, concern that has a concrete definable fix. Some common names include: service request, work order or ticket. Citizen Any natural person. Non-Governmental Organization An entity that is not a government. Government The organization that manages a political unit of any size. Locale The collection of configuration that is necessary to contextualize specific content for a particular language format. For example language or numerical formatting that configures a system for a specific known language. Locales are usually originated in a specific geographic region. However the Open311 API expects them to only refer to the configuration necessary localize content for that locale. See http://en.wikipedia.org/wiki/Locale Latitude / Longitude All latitudes and longitude values MUST be WGS84 (World Geodetic System 1984) datum values expressed in decimal format. See http://en.wikipedia.org/wiki/WGS84 For Example: 37.40320,-121.977521 Area of Interest An area of interest is a bounded geographical area inside which a service provider will accept issue reports. Areas of interest are independent of the locales that a provider supports. Providers MAY support any area(s) of interest independently of which ever locale(s) they wish to support. Root URI A root URI defines the start point for the API for a particular service provider. It is defined by the service provider and takes the form of: http://<host>[/path] Possible Example Root URIs:    http://api.seeclickfix.com/open311/    http://data.gov/apis/311/    http://311.toronto.ca/ Protocol Overview The Open311 API is stateless. Protocol Messages Open311 messages are mappings of plain-text parameters (keys) to plain-text values. The keys and values permit the full Unicode character set (UCS). When the keys and values need to be converted to/from bytes, they MUST be encoded using <a class=info href=http://openid.net/specs/openid-authentication-2_0.html#RFC3629>UTF-8 (Yergeau, F., “UTF-8, a transformation format of Unicode and ISO 10646,” .)</a> [RFC3629]. Messages MUST NOT contain multiple keys with the same name. Throughout this document, all Open311 parameters are REQUIRED unless marked as OPTIONAL with square brackets eg [example] Open311 expects RESTful semantics on all URIs exposed by providers. This means that all GET requests MUST be idempotent. Said another way, GET requests return data with out making any change to the data at the service provider. To change data at a service provider the client must use a PUT, POST, or DELETE request. HTTP Encoding When a message is sent to an HTTP server, it MUST be encoded using a form encoding specified in Section 17.13.4 of <a class=info href=http://openid.net/specs/openid-authentication-2_0.html#HTML401>[HTML401] (W3C, “HTML 4.01 Specification,” .)</a>. Likewise, if the "Content-Type" header is included in the request's headers, its value MUST also be of such an encoding. Locale The Open311 API is intended for planet wide applicability. It is expected that there will be service providers that only support a single language locale. This locale MAY or MAY NOT be the primary locale for the areas of interest the service provider supports. It is also expected that there will be service providers that support several locales. Again these locales MAY or MAY NOT be the default primary locale for the areas of interest the service provider supports. If a client submits a request a service provider with no locale defined, then the service provider's response MUST be consistent with the default locale the service provider returns from the "/info" resource. If a client submits a request to a service provider with a locale that is included in the provider's list of supported locales then the service providers response MUST be consistent with the language locale specified in the request. If a client submits a request to a service provider with a locale that is not included in the provider's list of supported locales then the service provider's response MAY be consistent with any language locale that the service provider supports. Locale values MUST conform to [RFC 4646] definitions. See http://tools.ietf.org/html/rfc4646 Resources Any request or response parameters marked in square brackets like this: [example], MUST be considered optional. All other parameters MUST be considered required. Resource URIs MAY be suffixed with the format the client prefers to receive its response. Clients SHOULD NOT request any formats other then:    -JSON    -HTML    -XML Providers SHOULD respond to these requests with properly formatted responses. If no format is specified then the service provider SHOULD respond with an HTML formatted response. The implementation of the HTML response is intended to be human read-able. The specific format of which is left to the discretion of the service provider. Clients SHOULD NOT expect the format of the HTML responses to be be consistent between service providers or through time for the same service provider. /versions Description This base resource is intended to be used to provide clients with information on which versions of the Open311 API the provider supports. GET Accepts:     -no parameters- Returns:     versions: List of supported API versions Example Request:     http://api.provider.gov/open311/info.json Response:     { "versions" : ["v1"] } PUT / POST / DELETE Not supported. /v1/info Description The info method is intended to return general system level information about the service provider. If no areas of interest are returned it is expected that the provider is interested in service requests in all areas. The provider doesn't return a list of areas of interested they SHOULD NOT error a service request create method for not existing inside an area of interest. GET Accepts:     [locale] Returns:     name: Provider Name     contact_info: Provider Contact Info         MUST include one of the following: phone, email or postal address     default_locale: Default Locale     locales: List of Supported Locales     areas: List of areas of interest         Each list of lat/lngs MUST be defined clockwise so as to disambiguate in vs out         Each list is a string of space delimited comma seperated pairs of latitude,longitude Example Request:     http://api.provider.gov/open311/v1/info.json Response: {     "name" : "Provider Gov",     "contact_info" : "Phone: +1 (123) 456 - 7890",     "default_locale" : "en-US",     "locales" : ["en-US", "en-CA"],     "areas" : ["37.40320,-121.977521 37.40320,-121.976021 37.40195,-121.976021 37.40195,-121.977521"] } PUT / POST / DELETE Not supported. /v1/issue GET Accepts:     [locale] Returns:     Success         issues: List of issues     Failure         locale         Error Description PUT Accepts:     [locale]: Language locale desired in reponse     summary: Short title for the issue.     [description]: Longer write up of exactly what the issue pertains to.     tags: comma delimited list of tags to apply to the issue.     display_name: How the reporter wishes to be identified as the reporter     lat: The latitude of the issue     lng: The longitude of the issue     [callback]: URI that the client requests notification calls be sent to in the event of this issue being updated. Returns:     Success         Same as GET to http://<root>/v1/issue/<id>     Failure         locale         Error Description POST / DELETE Not supported. /v1/issue/<id> This resource represents a specific issue inside of the service provider's system. The id is defined by the service provider at the time the issue is created. The id MUST stay consistent so that the same id always points to the same issue. The service provider MUST ensure that the id is unique inside of its own system and across versions of the API.  It is not expected that the id is unique accross service providers. GET Accepts:     [locale]     summary     description     tags     callback URI     display name     lat/lng Returns:     Success         request id     Failure         Error Code         Error Description /v1/tag Many municipalities or other governmental organizations have extensive internal taxonomies for issue classification. The Open311 API intentionally eschews rigid taxonomies. Instead the API supports free form tagging. To allow providers to help promote a coherent tag structure for submitted issues, providers MAY support this resource. If providers do not implement this then they MUST provide an empty list with an unsupported operation HTTP response code. If the client makes a call to this resource it gives the provider an opportunity to suggest a list of possible tag completion values that the provider would encourage the client to submit. The client MAY use a value from this returned list. The provider MUST accept any tag that is submitted by the client. GET Accepts:     [locale]: The desired language locale for the response.     [tag]: Some or no portion of a tag Returns:     Success         Ordered list of suggested tags     Failure         Locale         Error Description PUT / POST / DELETE Not supported. /v1/callback/<source URI>/<resource>... This is the resource that will be called by a client if that client was a provider that had a callback registered with it for the provider URI that it is now calling. To register a call back the caller MUST provide a URI. This URI MUST refer to a Open311 compliant provider system. If the service provider accepts the registration of a callback URI on a service request, the provider MUST make calls to the URI when state on that service request changes. Example: System A calls System B with a PUT: (only the callback is listed for simplicity)     Request: http://systemb.net/api/issue?callback=http://systemA.net/open311/     Response: { "id" : "12345678" } Some internal work flow changes the status of http://systemb.net/api/issue/12345678 from "Open" to "Closed". System A MUST call System B with the following POST:     Request: http://systemA.net/open311/callback/systemb.net/api/issue/12345678?status=Closed /v1/search The purpose of the search method is to return data associated with a service requests that match the query submitted. The specific algorithm for matching the query submitted to particular issues is solely at the discretion of the provider. It is SUGGESTED that the algorithm maintain consistency between searches that are performed soon after each other. However clients SHOULD NOT expect to always get the same result set back for the same query from the same provider. Each provider MAY implement rate limiting or max result set sizing in order to better shape the load on their system. GET Accepts:     [locale]     query: The query string Returns:     Success         List of issues     Failure         locale         Error Description PUT / POST / DELETE Not supported. /v1/find The purpose find resource is find issues that match the particular attributes that are submitted. GET Accepts:     [locale]     [bounding_box] (max lat, max lng, min lat, min lng)     [tags]     [keywords]     other attributes of issue? Returns:     Success         List of issues     Failure         locale         Error Description PUT / POST / DELETE Not supported. Acknowledgments This work attempts to stand on the shoulders of giants. Taking a stab at a thank you list would inevitability leave out a worthy party. This spec is not intended to promote an original idea, on the contrary, it is intended to codify the thinking of many others. Thank you to all. We would be remiss if we did not mention that the language in this spec is _heavily_ borrowed from the OpenID Authentication 2.0 Specification. Much appreciation is directed to their efforts. Open Questions Authentication     Q: How do we handle authentication?     Q: Is it required of optional? Authorization     Q: How do we handle API keying?     Q: Is it required or optional?     Q: Should there be an automated request/response mechanism in the API?     Q: Are providers allowed to rate limit clients? If so are there guidelines? Errors     Q: Should all messages return status 200?     Q: Should all error messages be human readable?     Q: Should all error messages be localized to the requested or default locale? Client Based Request Identifiers     Q: Would supporting client based request identifiers that allow clients to replay requests without repetitive effects be worth while?     Q: How long is the provider expected to track these Refusal of Service     Q: May providers refuse service at their discretion?     Q: Does the type of provider entity matter?     Q: How does a service provider reject PUT/POST/DELETE? Do rejects trigger callbacks? Comments     Q: Is the initial description considered a comment on the issue?     Q: Can anyone add comments to issues? </body> </html>

Thu Jun 18 23:40:18 UTC 2009

Open311 API Spec

Thu Jun 18 23:41:10 UTC 2009