I do like the idea of metadata at the top of a response for the reasons specified in 18F's standards.

While the 18F standards do not take a position on whether to use API keys, I do.

We will enforce their use for the sake of metrics, and a lesser extent, security.

Server-Side & Development

Always use HTTPS
At a minimum, 2048 Bit encryption is recommended for data transaction.
Authentication
Use HTTP Header to authenticate as an acceptable means of authentication
Session
Store session transactions on a per click basis.
Error Handling
100: = 'Continue'
101: = 'Switching Protocols'
200: = 'OK'
201: = 'Created'
202: = 'Accepted'
203: = 'Non-Authoritative Information'
204: = 'No Content'
205: = 'Reset Content'
206: = 'Partial Content'
300: = 'Multiple Choices'
301: = 'Moved Permanently'
302: = 'Moved Temporarily'
303: = 'See Other'
304: = 'Not Modified'
305: = 'Use Proxy'
400: = 'Bad Request'
401: = 'Unauthorized'
402: = 'Payment Required'
403: = 'Forbidden'
404: = 'Not Found'
405: = 'Method Not Allowed'
406: = 'Not Acceptable'
407: = 'Proxy Authentication Required'
408: = 'Request Time-out'
409: = 'Conflict'
410: = 'Gone'
411: = 'Length Required'
412: = 'Precondition Failed'
413: = 'Request Entity Too Large'
414: = 'Request-URI Too Large'
415: = 'Unsupported Media Type'
500: = 'Internal Server Error'
501: = 'Not Implemented'
502: = 'Bad Gateway'
503: = 'Service Unavailable'
504: = 'Gateway Time-out'
505: = 'HTTP Version not supported'

I'm sympathetic to the JSON-only approach because I believe our standards should be forward-looking, not centered on the past.

However, in the migration from V1 to V2, I think it could do some harm if we just pulled the rug out from under those who use our data in XML format.

Thus, I would suggest XML becomes a secondary option, with JSON as the default.

1. Regarding error handling and authentication, we noticed that in current V1 implementation, if an application key is required for request, failure to send the required key results in 404 instead of the more appropriate status code, i.e. 403. We recommend that V2 take this aspect of error
   handling into consideration.
2. It may be desirable for the V2 implementation provide a convenient way for client to detect and download new data. From the client perspective, one of the common use case may be for the client to store the downloaded data locally and then to download from the DOL API site for new data regularly. Since the server does not track clients' data download, it is the client responsibility to find new data via search, for example. It would be more convenient if the client can find the data count for any given search via some kind of common URI pattern, e.g. http://api.dol.gov/V1/DOLAgency/Agencies/$count?a=b&c=d This way, client can more easily compare search hits without actually having to download the data sets and this also alleviate the load on the server and the associated back end database since select count(*) will be much cheaper than select *. The count API method also make it possible for client to implement smart paging without having to store the data locally.
3. Regarding security, we recommend the server host the API to remove all unnecessary method from server configuration, i.e. if, DELETE is not used by the server, remove it from configuration.
4. Regarding caching. Will the v2 design consider caching for the most frequently requested data sets. Caching can provide not only performance boost but also alleviation to the affected back end database.
5. Regarding the "Just use JSON" practice, we like to point out that the current V1 implementation use XML as default and there are probably clients who already build application using XML. While there are some benefits for supporting just JSON, XML as a more robust data standard also
   deserve some consideration on many merits, things that are easily achieved with XML, e.g. data validation and transformation via xsd are just a few to name. Also if the API were to provide bulk download in the future, a more compact data format such as csv may be much more efficient.
6. Regarding the "API End Points". We'd like to point out that the HTTP "accept" header could also be considered a relevant element. It is conceivable for the same Method/URI, a different server side
   handler/endpoint is used for different accept data format, e.g. one for xml, one for json, and another for csv.
7. Regarding the use of API keys, we noticed that the current V1 implementation pass API keys as part of query string. It is not a secure way to pass authentication credential since the KEY is clearly visible as part of browser URL and therefore in browser history. Since V1 also allow HTTP, it makes the KEY vulnerable. We recommend that if V2 were to use API keys, make it a custom header instead of part of the query string.

Advanced Engineering Group, OCIO, DOL

We should remove the Pagination section if we strongly feel that we can support bulk data requests going forward.