Skip to content

Instantly share code, notes, and snippets.

@zdne
Created February 25, 2016 14:42
Show Gist options
  • Save zdne/d81c1556567f0b75ea9b to your computer and use it in GitHub Desktop.
Save zdne/d81c1556567f0b75ea9b to your computer and use it in GitHub Desktop.
# API
## Globals Parameters
- version: 1.0 (string) - Version of the API
# Resource A [/{version}/some/path/to/a]
# Resource B [/{version}/some/path/to/b]
# Resource C [/{version}/c]
@TwinbrotherPro
Copy link

Are you now talking about a modification of the BluePrint specification or is this solution acutally possible?

It may be a bether solution to put the version segment as a suffix at the host url. Is it possible to use global parameters for that too?

When i talked about the abstraction between endpoint version and path segment of the ressource i thought about considering the hypemedia principle in the RESTfull paradigm, which may gets disregared by appending the version to the uri path of the ressource.

I know, that using a description langauge like API Blueprint Swagger or RAML always restricts the Hypermedia principle, but its a good way always searching for the best compromise by respecting all principles of the REST-Paradigm and providing a contract between service user and provicer.

@zdne
Copy link
Author

zdne commented Mar 5, 2016

This was just a sketch of an idea.

Frankly I'd like to avoid building a facility for URL "versioning" in the API Blueprint since I do not want to encourage it at the expense of other methods (https://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown).

So that is why I am looking a more generic solution that would also address this. Looking into near future apiaryio/api-blueprint#286 should bring MSON syntax to URI parameters / path segments so introducing a global variables could be one way to go...

From a Hypermedia standpoint it does not really matter what the value URL has. I like your point on looking for a compromise tho!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment