brayzen/gist:f235035d316b92e02dea

## gistfile1.txt
API versioning:

WHAT? and WHY?
  We're talking about having an application programming interface that spits out JSON for other applications to use.  Inevitably, as a developer, looking for better names, and better ways of doing something is a constant theme.  It becomes contentious because any developer knows that changing something inevitably means something else will break.  Thus the need to keep support for an old version and make changes to a new version.

HOW?:
  I found a well written article (www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-is.html?m=1) that sort of walks through the different methods by which a developer can instantiate a new version for his/her API.
  1st Option: CHANGE THE URL.....his example was something like example.com/api/v2
    Pros: easy
    Cons: namespace doesn't seem to match up (kluegy)
  2nd Option: Custom request header: You use the same URL as before but add a header such as “api-version: 2”
    Cons: semantically incorrect
  3rd Option: Accept header: You modify the accept header to specify the version, for example “Accept: application/vnd.haveibeenpwned.v2+json”
    Cons: not easy, developers now have to make a carefully constructed header and be exact

The summarry is that no way is better than the others.  Though I felt more of an inclination for the URL, but instead of putting in the URI, I took the approach of changing the subdomain.  For future versions, instead of https://api.example.com, the new version could be reached at https://apiv2.example.com.

Sounds like the most important point is to have your new version well documented and make it as easy as possible for the developers who have taken the time to write code for your API.
	API versioning:

	WHAT? and WHY?
	We're talking about having an application programming interface that spits out JSON for other applications to use. Inevitably, as a developer, looking for better names, and better ways of doing something is a constant theme. It becomes contentious because any developer knows that changing something inevitably means something else will break. Thus the need to keep support for an old version and make changes to a new version.

	HOW?:
	I found a well written article (www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-is.html?m=1) that sort of walks through the different methods by which a developer can instantiate a new version for his/her API.
	1st Option: CHANGE THE URL.....his example was something like example.com/api/v2
	Pros: easy
	Cons: namespace doesn't seem to match up (kluegy)
	2nd Option: Custom request header: You use the same URL as before but add a header such as “api-version: 2”
	Cons: semantically incorrect
	3rd Option: Accept header: You modify the accept header to specify the version, for example “Accept: application/vnd.haveibeenpwned.v2+json”
	Cons: not easy, developers now have to make a carefully constructed header and be exact

	The summarry is that no way is better than the others. Though I felt more of an inclination for the URL, but instead of putting in the URI, I took the approach of changing the subdomain. For future versions, instead of https://api.example.com, the new version could be reached at https://apiv2.example.com.

	Sounds like the most important point is to have your new version well documented and make it as easy as possible for the developers who have taken the time to write code for your API.