whitehouse/api-standards

api-standards's Issues

Mention this as a nice-to-have

• Related - a mention to the genearl design pattern that if I have a resource (e..g, a blog post), I should just be able to add .json to the same URL and get it in the format I want (or .xml, etc.) Each resource has a URL, regardless of format be it human readable or machine readable

License for the content

We are planning to use your standard as base for X-Road REST API Standards in Finland (https://github.com/educloudalliance/api-standards/blob/master/README.md). We were not able to find license for the content. Rather than assuming that content is public domain, we would like to know if you have considered license for the material? Perhaps CC license? Knowing it would make our life easier.

Please update readme with correct apigee links

http://apigee.com/about/resources/ebooks/api-fa%C3%A7ade-pattern -> https://pages.apigee.com/rs/apigee/images/api-facade-pattern-ebook-2012-06.pdf
http://pages.apigee.com/web-api-design-ebook.html -> https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf

Consider using the IETF API-Problem specification for error messages

Referring to the https://github.com/WhiteHouse/api-standards#error-handling section, it is great that the WH API standards promote helpful error messages for developers who consume the APIs. Have you considered adopting the IETF API-Problem specification? It appears to be similar in goals to what WH is trying to do, but it might be good to adopt a standard response format. There is a relevant blog post at http://www.mnot.net/blog/2013/05/15/http_problem, and there is some PHP tooling around the spec at https://github.com/Crell/ApiProblem.

Thanks!
Chris

Clarify how JSONP URLs are constructed

The example of JSONP usage doesn't include a file format extension in the URL. Should this extension be .json or .jsonp? I would recommend .jsonp since it effectively behaves like a different format

Thanks and FYI

Hi @WhiteHouse.

18F published its initial API Standards, a process that began with forking your great work. Thank you very much for your leadership in this area and let us know if you want us to submit the individual sections as pull requests for conversation here.

Suggestion from Twitter re. HTTP status.

Colin ‏@colinfrei

@whWeb looks cool! I'd suggest requiring that calls should return a correct HTTP
status,right now it seems it only has to be in the response

Http Code In response Json is useless

this is really useless

Recommend how capitalization is handled

URLs, XML, and JSON are all case sensitive. In many programing languages like javascript camel case is preferred for variable names, but API resources specified in a URL are often preferred to be all lowercase and hyphen separated, while the names of values in json are often lowercase and underscore separated. This seems to be the implied convention based on the examples shown and matches my own personal preference, but this should be clarified. Camel case seems appropriate as code, but not as data.

Some questions on the directory structure

Hello, We're trying to finalize the API directory structure here at the U.S. Patent and Trademark Office--based on your examples--and have some questions on the examples. So that we're sure we're understanding them correctly, any chance you have time for questions? Thanks, Arva

Add rationale to some guidelines.

I have found this a great resource when defining REST APIs. One small thing.

In the responses section, it is stated that "No values in keys". Whilst I agree with this, and get some way in being able to clearly articulate why, it would be good to ensure that the rationale behind the standard is captured and documented.

JSONP

json-p is being replaced by CORS because of security issues. Please remove this section or at least mention this fact.

P.S. Thanks for this awesome page :)

A few CDC Enhancements

At CDC we have been working developers at HHS and codeveloping our new API with this specification on our Content Services project. We have two suggested enhancements.

1. Allowing for multiple message returns in the JSON return set to provide independent information for bulk actions and where possible deeper information to the caller.
   "status":200,"message":[],
2. Move the pagination information into a separate structure to better delineate it and provide more navigation information.

pagination":{"count":3384,
"offset":0,
"page":1,
"max":2,
"totalPages":1692,
"sort":"datepublished Desc",
"currentUri":"http://prototype.cdc.gov/api/v1/resources/media/?max=2",
"previousUri":null,
"nextUri":"http://prototype.cdc.gov/api/v1/resources/media/?max=2&page=2&rsid=e5f13d08-fd94-413e-ae0e-9112c5c88415"}
}

POST request payload, format, and behavior are not clearly specified

It's not clear if the example of json data for POST /magazines/[id]/articles is the payload sent as the POST request or if its the response from a successful POST request, or both. Typical POST requests with an HTML webform are sent as application/x-www-form-urlencoded and that is specified in the header. I'm guessing the example shown is sent as json, but that should be clarified. If these guidelines are agnostic about how POST requests are made in the same way they're agnostic about xml or json responses, then perhaps it should discuss how people can know the options available. Perhaps specifying the format as an extension in the URL is used not only to indicate the response format, but also the payload being sent in the request.

CORS?

This is just my personal opinion so please feel free to take with a grain of salt, but I have found many API designers share it, so for whatever it's worth:

You may not need JSONP if you enable CORS Access-Control-Allow-Origin: * (http://en.wikipedia.org/wiki/Cross-origin_resource_sharing) in all your API responses.

Enabling it does not decrease the security of your API wee bit (many would argue JSONP is less secure) and removes a lot of complexity.

Recommend encoding type

I would suggest UTF-8 and this should be specified in the HTTP Content-Type header as well, eg for json the full header would be

Content-Type: application/json; charset=utf-8

See http://utf8everywhere.org/ for some arguments for UTF-8 and arguments against other encodings like UTF-16

What is the license?

Is it GPLv3 compatible?

Accept-type headers

Accept-type headers - In addition to appending .json, I should also be able to send accept-type "application/json". Makes working with Backbone and other client-side libraries a lot easier.

POST response format and behavior is not specified

The URL examples show that the GET response format is specified with a file extension like .json or .xml, but no extension is shown for the POST example and there's no explanation of the behavior of a successful POST response. I would suggest that the format for POST responses is specified the same way as GET responses so that an error message or a success message will be returned with the desired format.

Note that specifying this response format could be completely independent from the format of the actual payload sent in the POST request. That's not specified here anywhere either, but I'll note that as a separate issue.

Broken link

The link in README.md http://apigee.com/about/content/api-fa%C3%A7ade-pattern does not work.

JSONP, Access Control Allow Origin

Would be cool to give JSONP and Access Control Allow Origin a shout out (unless I missed it?). As a frequent consumer of government APIs, not being able to do things client side is a huge barrier to quick, cool projects.

Extending guidelines to include APIs that need authentication and authorization

Would you consider providing guidelines to include RESTful APIs that requires user authentication and data access authorization?

For example, how would you ensure I was Steve and when I request "/dogs" I only received my dogs?

Additional common/important HTTP Response Codes

200 OK: Success!

201 Created: a common return code for a successful HTTP POST (or PUT in idempotent creations)

202 Accepted: request was accepted, but has not fully been processed, yet. A common code to return for asynchronous calls.

304 Not Modified: There was no new data to return (think: cache). <-- This is very important!

400 Bad Request: Invalid Request. Error message will be returned to provide further details.

401 Unauthorized: Authentication credentials were missing or incorrect.

403 Forbidden: Valid request that was refused. Attempt to access a resource that the client does not have permission to. Error message will be returned to provide further details.

404 Not Found: The URL requested is invalid or the resource requested, such as a document or a user, does not exists.

406 Not Acceptable: Returned when parameters passed are correct in theory and individually, but when combined can not be satisfied because the combination makes no sense (e.g. cart_id from one user is used with a user_id from another user). If possible, an error message will be returned to provide further details.

500 Internal Server Error: Something went horribly wrong and we were not smart enough to provide more details :) Hopefully a very rare response code.

503 Service Unavailable: Servers are offline for maintenance or went down under load (oops).

Email confirmation RESTful api

I'm trying to create a new endpoint for confirming email after registering new user but I doubt if it's right or not?
Here is what I have in my mind :

/users/{id}/confirmations/{token}

• "confirmation" or "confirmations" ?
• When the endpoint is a resource? is "confirmation" a resource?

POST is not always "create" and PUT is not always "update".

This is somewhat minor, but the document says that HTTP POST is a "Create". That is not correct. There is no one-to-one mapping between CRUD and HTTP verbs. It boils down to whether the operation is idempotent or not.

HTTP POST is non-idempotent, HTTP PUT is idempotent.

As for CRUD: Create can be both idempotent (if you provide ID of the record that ought to be created, e.g. you are creating a user with specific user_id) or non-idempotent (if you provide data but not the ID). So there're many cases where PUT is absolutely fine for a Create operation.

Furthermore, many services do not support anything but GETor POST. This is because browsers do not support any other verb so lots of proxies and most CDNs also only implement GET and POST with zero support for anything else. We have had some conversations with major CDN providers to address this very issue and I know some of them are actively working on it. Point is: a lot of pragmatic APIs implement POST for "delete" and "update" with so-called Method Override.

Speaking of which, this document could probably use a word or two about method overrides.

JSON design patterns

JSON design patterns - JSON is awesome because it's free form, but there are certain design patterns (e.g., having URLs to all the related resources -- see e.g., GitHub's API which does this really well), and returning either an object (single record) or an array of objects (multiple records).

Write something about running multiple versions of the API

Should the new version (say v2) of the API be a route in the existing application, or it should be a new server and mapped to a route using nginx ?

Record limits are unclear as to if offset is zero based

In order to avoid confusion, I think it would be best to list what the default is. Therefore, if the records are zero based, it would make sense to specify that the default offset is 0

https://github.com/WhiteHouse/api-standards#record-limits

This is not "Truly Restful"

I would drop "truly RESTful API" mentioned couple times. Especially since you mention Roy's name in the same document. I don't want to speak for Roy, but considering his writing he would not call these guidelines RESTful at all. Case in point:
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Your document adheres to what a lot of people commonly call REST and what I used to call "pragmatic REST" years ago, but it's not Hypermedia APIs, which is what Roy would call "true REST".

Clarify file formats and use of Content-Type headers

The use of format terms like "XML" and "JSON" can be ambiguous without specifying HTTP Content-Type headers. I would also recommend specifying the character encoding here, but I'll mention that as another issue. I would recommend XML and JSON usage as the following types and the guidelines should articulate that HTTP headers should match this for each format.

XML: Content-Type: text/xml; charset=utf-8
JSON: Content-Type: application/json; charset=utf-8

Version in Accept Header rather than URL

Generally, it's better practice to put the version of the service in the HTTP Accept Header. The URL should uniquely identify the identities, independent of the representation of those entities on the wire. The version of the schema should be seen as a representation of the entities.