search

nasa / api-docs

api.nasa.gov
http://nasa.github.io/api-docs/
450 stars 109 forks source link

Consider version numbers in headers or the url #16

Closed gbinal closed 9 years ago

danhammer commented 9 years ago

question to answer: how do we add to the headers that are returned from api.data.gov?

gbinal commented 9 years ago

cc @gui

GUI commented 9 years ago

@danhammer: I may not be understanding the question entirely, but are you talking about request or response headers? In other words, the headers your API backend sees or the headers the user sees?

If you're talking about request headers, then you can add or modify the HTTP headers your API backend sees on the request by going into the Admin, and navigating to Configuration > API Backends. From there, select your API backend, and then under "Global Request Settings" there's a "Set Headers" field you can use to add new HTTP Headers.

If you're talking about the response headers, api.data.gov currently doesn't offer any capabilities to add headers to the response (we typically take a pretty hands-off approach on modifying your response in any fashion). So you'd typically have your actual API backend add any HTTP headers you wanted in the response. But if you do think having the ability to add HTTP headers at the api.data.gov layer would be useful, I'd love to better understand the use-case.

jasonduley commented 9 years ago

I am a fan of seeing them explicitly in the URL e.g.: http://api.nasa.gov/apod/v1/

GUI commented 9 years ago

For whatever it's worth, I'm also personally fan of URL-based versioning (the WH standards cover this practice pretty succinctly). Versioning in any fashion is a good thing, though, so if you prefer HTTP headers, that's certainly fine, but from my personal experience I've just found URL-based versioning a little more straightforward and practical for everyone involved (even if may not be quite as RESTful).

danhammer commented 9 years ago

I agree with you both. It's currently in the URL (behind the scenes). I wrote this issue to take notes on the feedback from our (awesome) Twilio developer/tester. Consider #16 considered.