Versioning formats for REST API
I try get into versioning strategies for REST API's following Microsoft REST API Guidelines and trying to utilize for my ASP.NET Core solution.
From the guide :
Two options for specifying the version of a REST API request are supported:
Embedded in the path of the request URL, at the end of the service root:
https://api.contoso.com/v1.0/products/users
As a query string parameter of the URL:
https://api.contoso.com/products/users?api-version=1.0
Guidance for choosing between the two options is as follows:
...
- Services that guarantee the stability of their REST API's URL paths, even through future versions of the API, MAY adopt the query string parameter mechanism. This means the naming and structure of the relationships described in the API cannot evolve after the API ships, even across versions with breaking changes.
- Services that cannot ensure URL path stability across future versions MUST embed the version in the URL path.
I think that I don't quite understand what does 'cannot evolve' means in -
This means the naming and structure of the relationships described in the API cannot evolve after the API ships, even across versions with breaking changes.
Could you please give a little expanded definition ?
And do you have any example of Services that cannot ensure URL path stability across future versions ?
Thank you : )
c# asp.net-core versioning
asked Oct 19 '18 at 11:45
Tomorrow's ExplorerTomorrow's Explorer
305
|
show 1 more comment
I try get into versioning strategies for REST API's following Microsoft REST API Guidelines and trying to utilize for my ASP.NET Core solution.
From the guide :
Two options for specifying the version of a REST API request are supported:
Embedded in the path of the request URL, at the end of the service root:
https://api.contoso.com/v1.0/products/users
As a query string parameter of the URL:
https://api.contoso.com/products/users?api-version=1.0
Guidance for choosing between the two options is as follows:
...
- Services that guarantee the stability of their REST API's URL paths, even through future versions of the API, MAY adopt the query string parameter mechanism. This means the naming and structure of the relationships described in the API cannot evolve after the API ships, even across versions with breaking changes.
- Services that cannot ensure URL path stability across future versions MUST embed the version in the URL path.
I think that I don't quite understand what does 'cannot evolve' means in -
This means the naming and structure of the relationships described in the API cannot evolve after the API ships, even across versions with breaking changes.
Could you please give a little expanded definition ?
And do you have any example of Services that cannot ensure URL path stability across future versions ?
Thank you : )
c# asp.net-core versioning
asked Oct 19 '18 at 11:45
Tomorrow's ExplorerTomorrow's Explorer
305
2
Don't use the minor version number. Urls with a dot in them are a bitch. Just use the major version number(/api/v1/controller/method)
– Archer
Oct 19 '18 at 11:51
I personally deem both as horrible by design ... A header telling what version you want would be more suited for REST applications as versiosn are neither resource access nor are they arguments relevant to the resource. But to expand definition, unstable URL paths is when stuff likefoo.com/items/1may change tofoo.com/products/1. You then should use the URL variant.
– X39
Oct 19 '18 at 11:51
@X39: headers are horrible idea imho, as they are hard to transport, don't work with get queries you paste into browser and make using of tools like swagger unnecessarily hard or even impossible. Swagger/OpenAPI UI has a ready to use documentation and tools to send out requests from within the swagger ui, can't remember theres been an easy way to set headers globally
– Tseng
Oct 19 '18 at 11:57
@Tseng your whole reason is "The APIs and tools are crap" ... Headers are easy to transport (the actual content actually is more complicated then "moving" headers from clients to servers) Only thing i agree on is that it is harder to use them for "new" APIs ... But even then, you always can use eg. nginx to setup subdomains for you and edit the header request version into it makingfoo.comtov1.foo.cometc. making that part problem-free again
– X39
Oct 19 '18 at 12:03
1
If you gonna translate hosts or urls with an reverse proxy to headers, then you can also just directly use it in the application as part of the path. The whole point about stable vs unstable API paths is that the url path doesn't change. Adding "v1" to the domain also changes the stability of the client, since the url changed too. query parameters on the other side aren't strictly part of the url path, they are more like filters (hence its name: query string)/api/products/2or/api/products/2?version=2still point to the same resource (thats what REST is about: Resources)
– Tseng
Oct 19 '18 at 12:12
|
show 1 more comment
I try get into versioning strategies for REST API's following Microsoft REST API Guidelines and trying to utilize for my ASP.NET Core solution.
From the guide :
Two options for specifying the version of a REST API request are supported:
Embedded in the path of the request URL, at the end of the service root:
https://api.contoso.com/v1.0/products/users
As a query string parameter of the URL:
https://api.contoso.com/products/users?api-version=1.0
Guidance for choosing between the two options is as follows:
...
- Services that guarantee the stability of their REST API's URL paths, even through future versions of the API, MAY adopt the query string parameter mechanism. This means the naming and structure of the relationships described in the API cannot evolve after the API ships, even across versions with breaking changes.
- Services that cannot ensure URL path stability across future versions MUST embed the version in the URL path.
I think that I don't quite understand what does 'cannot evolve' means in -
This means the naming and structure of the relationships described in the API cannot evolve after the API ships, even across versions with breaking changes.
Could you please give a little expanded definition ?
And do you have any example of Services that cannot ensure URL path stability across future versions ?
Thank you : )
c# asp.net-core versioning
asked Oct 19 '18 at 11:45
Tomorrow's ExplorerTomorrow's Explorer
305
I try get into versioning strategies for REST API's following Microsoft REST API Guidelines and trying to utilize for my ASP.NET Core solution.
From the guide :
Two options for specifying the version of a REST API request are supported:
Embedded in the path of the request URL, at the end of the service root:
https://api.contoso.com/v1.0/products/users
As a query string parameter of the URL:
https://api.contoso.com/products/users?api-version=1.0
Guidance for choosing between the two options is as follows:
...
- Services that guarantee the stability of their REST API's URL paths, even through future versions of the API, MAY adopt the query string parameter mechanism. This means the naming and structure of the relationships described in the API cannot evolve after the API ships, even across versions with breaking changes.
- Services that cannot ensure URL path stability across future versions MUST embed the version in the URL path.
I think that I don't quite understand what does 'cannot evolve' means in -
This means the naming and structure of the relationships described in the API cannot evolve after the API ships, even across versions with breaking changes.
Could you please give a little expanded definition ?
And do you have any example of Services that cannot ensure URL path stability across future versions ?
Thank you : )
c# asp.net-core versioning
c# asp.net-core versioning
asked Oct 19 '18 at 11:45
Tomorrow's ExplorerTomorrow's Explorer
305
asked Oct 19 '18 at 11:45
Tomorrow's ExplorerTomorrow's Explorer
305
asked Oct 19 '18 at 11:45
Tomorrow's ExplorerTomorrow's Explorer
305
asked Oct 19 '18 at 11:45
Tomorrow's ExplorerTomorrow's Explorer
305
asked Oct 19 '18 at 11:45
Tomorrow's ExplorerTomorrow's Explorer
305
305
2
Don't use the minor version number. Urls with a dot in them are a bitch. Just use the major version number(/api/v1/controller/method)
– Archer
Oct 19 '18 at 11:51
I personally deem both as horrible by design ... A header telling what version you want would be more suited for REST applications as versiosn are neither resource access nor are they arguments relevant to the resource. But to expand definition, unstable URL paths is when stuff likefoo.com/items/1may change tofoo.com/products/1. You then should use the URL variant.
– X39
Oct 19 '18 at 11:51
@X39: headers are horrible idea imho, as they are hard to transport, don't work with get queries you paste into browser and make using of tools like swagger unnecessarily hard or even impossible. Swagger/OpenAPI UI has a ready to use documentation and tools to send out requests from within the swagger ui, can't remember theres been an easy way to set headers globally
– Tseng
Oct 19 '18 at 11:57
@Tseng your whole reason is "The APIs and tools are crap" ... Headers are easy to transport (the actual content actually is more complicated then "moving" headers from clients to servers) Only thing i agree on is that it is harder to use them for "new" APIs ... But even then, you always can use eg. nginx to setup subdomains for you and edit the header request version into it makingfoo.comtov1.foo.cometc. making that part problem-free again
– X39
Oct 19 '18 at 12:03
1
If you gonna translate hosts or urls with an reverse proxy to headers, then you can also just directly use it in the application as part of the path. The whole point about stable vs unstable API paths is that the url path doesn't change. Adding "v1" to the domain also changes the stability of the client, since the url changed too. query parameters on the other side aren't strictly part of the url path, they are more like filters (hence its name: query string)/api/products/2or/api/products/2?version=2still point to the same resource (thats what REST is about: Resources)
– Tseng
Oct 19 '18 at 12:12
|
show 1 more comment
2
Don't use the minor version number. Urls with a dot in them are a bitch. Just use the major version number(/api/v1/controller/method)
– Archer
Oct 19 '18 at 11:51
I personally deem both as horrible by design ... A header telling what version you want would be more suited for REST applications as versiosn are neither resource access nor are they arguments relevant to the resource. But to expand definition, unstable URL paths is when stuff likefoo.com/items/1may change tofoo.com/products/1. You then should use the URL variant.
– X39
Oct 19 '18 at 11:51
@X39: headers are horrible idea imho, as they are hard to transport, don't work with get queries you paste into browser and make using of tools like swagger unnecessarily hard or even impossible. Swagger/OpenAPI UI has a ready to use documentation and tools to send out requests from within the swagger ui, can't remember theres been an easy way to set headers globally
– Tseng
Oct 19 '18 at 11:57
@Tseng your whole reason is "The APIs and tools are crap" ... Headers are easy to transport (the actual content actually is more complicated then "moving" headers from clients to servers) Only thing i agree on is that it is harder to use them for "new" APIs ... But even then, you always can use eg. nginx to setup subdomains for you and edit the header request version into it makingfoo.comtov1.foo.cometc. making that part problem-free again
– X39
Oct 19 '18 at 12:03
1
If you gonna translate hosts or urls with an reverse proxy to headers, then you can also just directly use it in the application as part of the path. The whole point about stable vs unstable API paths is that the url path doesn't change. Adding "v1" to the domain also changes the stability of the client, since the url changed too. query parameters on the other side aren't strictly part of the url path, they are more like filters (hence its name: query string)/api/products/2or/api/products/2?version=2still point to the same resource (thats what REST is about: Resources)
– Tseng
Oct 19 '18 at 12:12
2
2
Don't use the minor version number. Urls with a dot in them are a bitch. Just use the major version number
(/api/v1/controller/method)– Archer
Oct 19 '18 at 11:51
Don't use the minor version number. Urls with a dot in them are a bitch. Just use the major version number
(/api/v1/controller/method)– Archer
Oct 19 '18 at 11:51
I personally deem both as horrible by design ... A header telling what version you want would be more suited for REST applications as versiosn are neither resource access nor are they arguments relevant to the resource. But to expand definition, unstable URL paths is when stuff like
foo.com/items/1 may change to foo.com/products/1. You then should use the URL variant.– X39
Oct 19 '18 at 11:51
I personally deem both as horrible by design ... A header telling what version you want would be more suited for REST applications as versiosn are neither resource access nor are they arguments relevant to the resource. But to expand definition, unstable URL paths is when stuff like
foo.com/items/1 may change to foo.com/products/1. You then should use the URL variant.– X39
Oct 19 '18 at 11:51
@X39: headers are horrible idea imho, as they are hard to transport, don't work with get queries you paste into browser and make using of tools like swagger unnecessarily hard or even impossible. Swagger/OpenAPI UI has a ready to use documentation and tools to send out requests from within the swagger ui, can't remember theres been an easy way to set headers globally
– Tseng
Oct 19 '18 at 11:57
@X39: headers are horrible idea imho, as they are hard to transport, don't work with get queries you paste into browser and make using of tools like swagger unnecessarily hard or even impossible. Swagger/OpenAPI UI has a ready to use documentation and tools to send out requests from within the swagger ui, can't remember theres been an easy way to set headers globally
– Tseng
Oct 19 '18 at 11:57
@Tseng your whole reason is "The APIs and tools are crap" ... Headers are easy to transport (the actual content actually is more complicated then "moving" headers from clients to servers) Only thing i agree on is that it is harder to use them for "new" APIs ... But even then, you always can use eg. nginx to setup subdomains for you and edit the header request version into it making
foo.com to v1.foo.com etc. making that part problem-free again– X39
Oct 19 '18 at 12:03
@Tseng your whole reason is "The APIs and tools are crap" ... Headers are easy to transport (the actual content actually is more complicated then "moving" headers from clients to servers) Only thing i agree on is that it is harder to use them for "new" APIs ... But even then, you always can use eg. nginx to setup subdomains for you and edit the header request version into it making
foo.com to v1.foo.com etc. making that part problem-free again– X39
Oct 19 '18 at 12:03
1
1
If you gonna translate hosts or urls with an reverse proxy to headers, then you can also just directly use it in the application as part of the path. The whole point about stable vs unstable API paths is that the url path doesn't change. Adding "v1" to the domain also changes the stability of the client, since the url changed too. query parameters on the other side aren't strictly part of the url path, they are more like filters (hence its name: query string)
/api/products/2 or /api/products/2?version=2 still point to the same resource (thats what REST is about: Resources)– Tseng
Oct 19 '18 at 12:12
If you gonna translate hosts or urls with an reverse proxy to headers, then you can also just directly use it in the application as part of the path. The whole point about stable vs unstable API paths is that the url path doesn't change. Adding "v1" to the domain also changes the stability of the client, since the url changed too. query parameters on the other side aren't strictly part of the url path, they are more like filters (hence its name: query string)
/api/products/2 or /api/products/2?version=2 still point to the same resource (thats what REST is about: Resources)– Tseng
Oct 19 '18 at 12:12
|
show 1 more comment
1 Answer
1
active
oldest
votes
The Microsoft guidelines are recommending not using query parameters to control major versions if you anticipate changes to the resource names in the URLs themselves.
With path parameter versioning you could have:
https://api.contoso.com/v1.0/products/users
https://api.contoso.com/v2.0/items/customers
where with query parameters, they recommend changing the resource names, where some resources would only support some version parameters.
As @Archer says, the most common practice seems to be to use a major version without a dot or subversion, and query parameter versions are rare except for version date parameters like FourSquare's (https://developer.foursquare.com/docs/api/configuration/versioning), which is typically used in addition to a major path version, and typically controls smaller API changes than resource name changes.
answered Nov 13 '18 at 18:57
Jeffrey StylosJeffrey Stylos
1386
add a comment |
Your Answer
StackExchange.ifUsing("editor", function () {
StackExchange.using("externalEditor", function () {
StackExchange.using("snippets", function () {
StackExchange.snippets.init();
});
});
}, "code-snippets");
StackExchange.ready(function() {
var channelOptions = {
tags: "".split(" "),
id: "1"
};
initTagRenderer("".split(" "), "".split(" "), channelOptions);
StackExchange.using("externalEditor", function() {
// Have to fire editor after snippets, if snippets enabled
if (StackExchange.settings.snippets.snippetsEnabled) {
StackExchange.using("snippets", function() {
createEditor();
});
}
else {
createEditor();
}
});
function createEditor() {
StackExchange.prepareEditor({
heartbeatType: 'answer',
autoActivateHeartbeat: false,
convertImagesToLinks: true,
noModals: true,
showLowRepImageUploadWarning: true,
reputationToPostImages: 10,
bindNavPrevention: true,
postfix: "",
imageUploader: {
brandingHtml: "Powered by u003ca class="icon-imgur-white" href="https://imgur.com/"u003eu003c/au003e",
contentPolicyHtml: "User contributions licensed under u003ca href="https://creativecommons.org/licenses/by-sa/3.0/"u003ecc by-sa 3.0 with attribution requiredu003c/au003e u003ca href="https://stackoverflow.com/legal/content-policy"u003e(content policy)u003c/au003e",
allowUrls: true
},
onDemand: true,
discardSelector: ".discard-answer"
,immediatelyShowMarkdownHelp:true
});
}
});
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
StackExchange.ready(
function () {
StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fstackoverflow.com%2fquestions%2f52891713%2fversioning-formats-for-rest-api%23new-answer', 'question_page');
}
);
Post as a guest
Required, but never shown
1 Answer
1
active
oldest
votes
1 Answer
1
active
oldest
votes
active
oldest
votes
active
oldest
votes
The Microsoft guidelines are recommending not using query parameters to control major versions if you anticipate changes to the resource names in the URLs themselves.
With path parameter versioning you could have:
https://api.contoso.com/v1.0/products/users
https://api.contoso.com/v2.0/items/customers
where with query parameters, they recommend changing the resource names, where some resources would only support some version parameters.
As @Archer says, the most common practice seems to be to use a major version without a dot or subversion, and query parameter versions are rare except for version date parameters like FourSquare's (https://developer.foursquare.com/docs/api/configuration/versioning), which is typically used in addition to a major path version, and typically controls smaller API changes than resource name changes.
answered Nov 13 '18 at 18:57
Jeffrey StylosJeffrey Stylos
1386
add a comment |
The Microsoft guidelines are recommending not using query parameters to control major versions if you anticipate changes to the resource names in the URLs themselves.
With path parameter versioning you could have:
https://api.contoso.com/v1.0/products/users
https://api.contoso.com/v2.0/items/customers
where with query parameters, they recommend changing the resource names, where some resources would only support some version parameters.
As @Archer says, the most common practice seems to be to use a major version without a dot or subversion, and query parameter versions are rare except for version date parameters like FourSquare's (https://developer.foursquare.com/docs/api/configuration/versioning), which is typically used in addition to a major path version, and typically controls smaller API changes than resource name changes.
answered Nov 13 '18 at 18:57
Jeffrey StylosJeffrey Stylos
1386
add a comment |
The Microsoft guidelines are recommending not using query parameters to control major versions if you anticipate changes to the resource names in the URLs themselves.
With path parameter versioning you could have:
https://api.contoso.com/v1.0/products/users
https://api.contoso.com/v2.0/items/customers
where with query parameters, they recommend changing the resource names, where some resources would only support some version parameters.
As @Archer says, the most common practice seems to be to use a major version without a dot or subversion, and query parameter versions are rare except for version date parameters like FourSquare's (https://developer.foursquare.com/docs/api/configuration/versioning), which is typically used in addition to a major path version, and typically controls smaller API changes than resource name changes.
answered Nov 13 '18 at 18:57
Jeffrey StylosJeffrey Stylos
1386
The Microsoft guidelines are recommending not using query parameters to control major versions if you anticipate changes to the resource names in the URLs themselves.
With path parameter versioning you could have:
https://api.contoso.com/v1.0/products/users
https://api.contoso.com/v2.0/items/customers
where with query parameters, they recommend changing the resource names, where some resources would only support some version parameters.
As @Archer says, the most common practice seems to be to use a major version without a dot or subversion, and query parameter versions are rare except for version date parameters like FourSquare's (https://developer.foursquare.com/docs/api/configuration/versioning), which is typically used in addition to a major path version, and typically controls smaller API changes than resource name changes.
answered Nov 13 '18 at 18:57
Jeffrey StylosJeffrey Stylos
1386
answered Nov 13 '18 at 18:57
Jeffrey StylosJeffrey Stylos
1386
answered Nov 13 '18 at 18:57
Jeffrey StylosJeffrey Stylos
1386
answered Nov 13 '18 at 18:57
Jeffrey StylosJeffrey Stylos
1386
1386
add a comment |
add a comment |
Thanks for contributing an answer to Stack Overflow!
- Please be sure to answer the question. Provide details and share your research!
But avoid …
- Asking for help, clarification, or responding to other answers.
- Making statements based on opinion; back them up with references or personal experience.
To learn more, see our tips on writing great answers.
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
StackExchange.ready(
function () {
StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fstackoverflow.com%2fquestions%2f52891713%2fversioning-formats-for-rest-api%23new-answer', 'question_page');
}
);
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
2
Don't use the minor version number. Urls with a dot in them are a bitch. Just use the major version number
(/api/v1/controller/method)– Archer
Oct 19 '18 at 11:51
I personally deem both as horrible by design ... A header telling what version you want would be more suited for REST applications as versiosn are neither resource access nor are they arguments relevant to the resource. But to expand definition, unstable URL paths is when stuff like
foo.com/items/1may change tofoo.com/products/1. You then should use the URL variant.– X39
Oct 19 '18 at 11:51
@X39: headers are horrible idea imho, as they are hard to transport, don't work with get queries you paste into browser and make using of tools like swagger unnecessarily hard or even impossible. Swagger/OpenAPI UI has a ready to use documentation and tools to send out requests from within the swagger ui, can't remember theres been an easy way to set headers globally
– Tseng
Oct 19 '18 at 11:57
@Tseng your whole reason is "The APIs and tools are crap" ... Headers are easy to transport (the actual content actually is more complicated then "moving" headers from clients to servers) Only thing i agree on is that it is harder to use them for "new" APIs ... But even then, you always can use eg. nginx to setup subdomains for you and edit the header request version into it making
foo.comtov1.foo.cometc. making that part problem-free again– X39
Oct 19 '18 at 12:03
1
If you gonna translate hosts or urls with an reverse proxy to headers, then you can also just directly use it in the application as part of the path. The whole point about stable vs unstable API paths is that the url path doesn't change. Adding "v1" to the domain also changes the stability of the client, since the url changed too. query parameters on the other side aren't strictly part of the url path, they are more like filters (hence its name: query string)
/api/products/2or/api/products/2?version=2still point to the same resource (thats what REST is about: Resources)– Tseng
Oct 19 '18 at 12:12