Name: api-standards
Owner: Campus Data
Description: null
Created: 2016-01-16 07:39:02.0
Updated: 2016-01-15 07:05:17.0
Pushed: 2015-12-23 17:30:55.0
Homepage: null
Size: 599
Language: null
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
This document provides guidelines and examples for White House Web APIs, encouraging consistency, maintainability, and best practices across applications. White House APIs aim to balance a truly RESTful API interface with a positive developer experience (DX).
This document borrows heavily from:
These guidelines aim to support a truly RESTful API. Here are a few exceptions:
HTTP verbs, or methods, should be used in compliance with their definitions under the HTTP/1.1 standard. The action taken on the representation will be contextual to the media type being worked on and its current state. Here's an example of how HTTP verbs map to create, read, update, delete operations in a particular context:
| HTTP METHOD | POST | GET | PUT | DELETE | | ———– | ————— | ——— | ———– | —— | | CRUD OP | CREATE | READ | UPDATE | DELETE | | /dogs | Create new dogs | List dogs | Bulk update | Delete all dogs | | /dogs/1234 | Error | Show Bo | If exists, update Bo; If not, error | Delete Bo |
(Example from Web API Design, by Brian Mulloy, Apigee.)
No values in keys:
"tags": [
{"id": "125", "name": "Environment"},
{"id": "834", "name": "Water Quality"}
],
Values in keys:
"tags": [
{"125": "Environment"},
{"834": "Water Quality"}
],
Error responses should include a common HTTP status code, message for the developer, message for the end-user (when appropriate), internal error code (corresponding to some specific internally determined ID), links where developers can find more info. For example:
{
"status" : 400,
"developerMessage" : "Verbose, plain language description of the problem. Provide developers
suggestions about how to solve their problems here",
"userMessage" : "This is a message that can be passed along to end-users, if needed.",
"errorCode" : "444444",
"moreInfo" : "http://www.example.gov/developer/path/to/help/for/444444,
http://drupal.org/node/444444",
}
Use three simple, common response codes indicating (1) success, (2) failure due to client-side problem, (3) failure due to server-side problem:
Information about record limits and total available count should also be included in the response. Example:
{
"metadata": {
"resultset": {
"count": 227,
"offset": 25,
"limit": 25
}
},
"results": []
}
Example: http://example.gov/api/v1/magazines.json
Response body:
{
"metadata": {
"resultset": {
"count": 123,
"offset": 0,
"limit": 10
}
},
"results": [
{
"id": "1234",
"type": "magazine",
"title": "Public Water Systems",
"tags": [
{"id": "125", "name": "Environment"},
{"id": "834", "name": "Water Quality"}
],
"created": "1231621302"
},
{
"id": 2351,
"type": "magazine",
"title": "Public Schools",
"tags": [
{"id": "125", "name": "Elementary"},
{"id": "834", "name": "Charter Schools"}
],
"created": "126251302"
}
{
"id": 2351,
"type": "magazine",
"title": "Public Schools",
"tags": [
{"id": "125", "name": "Pre-school"},
],
"created": "126251302"
}
]
}
Example: http://example.gov/api/v1/magazines/[id].json
Response body:
{
"id": "1234",
"type": "magazine",
"title": "Public Water Systems",
"tags": [
{"id": "125", "name": "Environment"},
{"id": "834", "name": "Water Quality"}
],
"created": "1231621302"
}
Example: Create ? POST http://example.gov/api/v1/magazines/[id]/articles
Request body:
[
{
"title": "Raising Revenue",
"author_first_name": "Jane",
"author_last_name": "Smith",
"author_email": "jane.smith@example.gov",
"year": "2012",
"month": "August",
"day": "18",
"text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam eget ante ut augue scelerisque ornare. Aliquam tempus rhoncus quam vel luctus. Sed scelerisque fermentum fringilla. Suspendisse tincidunt nisl a metus feugiat vitae vestibulum enim vulputate. Quisque vehicula dictum elit, vitae cursus libero auctor sed. Vestibulum fermentum elementum nunc. Proin aliquam erat in turpis vehicula sit amet tristique lorem blandit. Nam augue est, bibendum et ultrices non, interdum in est. Quisque gravida orci lobortis... "
}
]
It is suggested that each resource accept a 'mock' parameter on the testing server. Passing this parameter should return a mock data response (bypassing the backend).
Implementing this feature early in development ensures that the API will exhibit consistent behavior, supporting a test driven development methodology.
Note: If the mock parameter is included in a request to the production environment, an error should be raised.
JSONP is easiest explained with an example. Here's one from StackOverflow:
Say you're on domain abc.com, and you want to make a request to domain xyz.com. To do so, you need to cross domain boundaries, a no-no in most of browserland.
The one item that bypasses this limitation is
<script>
tags. When you use a script tag, the domain limitation is ignored, but under normal circumstances, you can't really DO anything with the results, the script just gets evaluated.Enter JSONP. When you make your request to a server that is JSONP enabled, you pass a special parameter that tells the server a little bit about your page. That way, the server is able to nicely wrap up its response in a way that your page can handle.
For example, say the server expects a parameter called “callback” to enable its JSONP capabilities. Then your request would look like:
http://www.xyz.com/sample.aspx?callback=mycallback
Without JSONP, this might return some basic javascript object, like so:
{ foo: 'bar' }
However, with JSONP, when the server receives the “callback” parameter, it wraps up the result a little differently, returning something like this:
mycallback({ foo: 'bar' });
As you can see, it will now invoke the method you specified. So, in your page, you define the callback function:
mycallback = function(data){ alert(data.foo); };
http://stackoverflow.com/questions/2067472/what-is-jsonp-all-about?answertab=votes#tab-top