One of the backlog items talks about API versioning:
(E2) As an application integrator, I would like to define what version of the API I support in order to be protected from API changes.
The currenting thinking I am hearing is that you could use the media type for this, but it would be easier to just use the URL Path
/candlepin/some/resource candlepin/v2/some/resource
where no v implies v1.
If folks are comfortable with that, it would mean no work until we do v2. I would move this off the backlog unless there were concerns.
Comments?
-- bk
The v2 in the URL is gross but it would help with keeping the code reusable I think as we could fork to different resources inheriting from common parent classes. Not sure if we could do the same with media type checking, at least not as easily.
Would the plain URL always be the latest and greatest with vX for those who want stability? Or is it no vX assumed to be v1 and we increment for all future releases.
On Tue, Apr 27, 2010 at 10:21 AM, Bryan Kearney bkearney@redhat.com wrote:
One of the backlog items talks about API versioning:
(E2) As an application integrator, I would like to define what version of the API I support in order to be protected from API changes.
The currenting thinking I am hearing is that you could use the media type for this, but it would be easier to just use the URL Path
/candlepin/some/resource candlepin/v2/some/resource
where no v implies v1.
If folks are comfortable with that, it would mean no work until we do v2. I would move this off the backlog unless there were concerns.
Comments?
-- bk _______________________________________________ candlepin mailing list candlepin@lists.fedorahosted.org https://fedorahosted.org/mailman/listinfo/candlepin
On Tue, Apr 27, 2010 at 10:26:40AM -0300, Devan Goodwin wrote:
The v2 in the URL is gross but it would help with keeping the code reusable I think as we could fork to different resources inheriting from common parent classes. Not sure if we could do the same with media type checking, at least not as easily.
Perhaps we could check the media type in a servlet filter and send the request to a completely different set of resources? I prefer the explicit version in the url, however.
Would the plain URL always be the latest and greatest with vX for those who want stability? Or is it no vX assumed to be v1 and we increment for all future releases.
You'd have to keep the plain url as v1 to not break existing clients.
On Tue, Apr 27, 2010 at 10:21 AM, Bryan Kearney bkearney@redhat.com wrote:
One of the backlog items talks about API versioning:
(E2) As an application integrator, I would like to define what version of the API I support in order to be protected from API changes.
The currenting thinking I am hearing is that you could use the media type for this, but it would be easier to just use the URL Path
/candlepin/some/resource candlepin/v2/some/resource
where no v implies v1.
If folks are comfortable with that, it would mean no work until we do v2. I would move this off the backlog unless there were concerns.
Comments?
-- bk _______________________________________________ candlepin mailing list candlepin@lists.fedorahosted.org https://fedorahosted.org/mailman/listinfo/candlepin
-- Devan Goodwin dgoodwin@rm-rf.ca http://rm-rf.ca _______________________________________________ candlepin mailing list candlepin@lists.fedorahosted.org https://fedorahosted.org/mailman/listinfo/candlepin
-James
On 04/27/2010 09:26 AM, Devan Goodwin wrote:
The v2 in the URL is gross but it would help with keeping the code reusable I think as we could fork to different resources inheriting from common parent classes. Not sure if we could do the same with media type checking, at least not as easily.
Well.. even with media-type=application/json+version2.0 we have issues with code re-use and refactoring
Would the plain URL always be the latest and greatest with vX for those who want stability? Or is it no vX assumed to be v1 and we increment for all future releases.
No v would be v1. Think of V1 as the fifth column.
-- bk
On Tue, Apr 27, 2010 at 10:26:40AM -0300, Devan Goodwin wrote:
The v2 in the URL is gross but it would help with keeping the code reusable I think as we could fork to different resources inheriting from common parent classes. Not sure if we could do the same with media type checking, at least not as easily.
Would the plain URL always be the latest and greatest with vX for those who want stability? Or is it no vX assumed to be v1 and we increment for all future releases.
based on bryan's email 'no v implies v1'.
What will our deprecation policy be? mark it deprecated and it gets removed in the next version?
Also, having the v2 in front of the resources makes it a little harder to reuse code, but how many versions will we have? 2? 3? n? I'm thinking no more than 3, personally 2 would be great.
If the v2 was after the resource we could actually reuse the same Resouce classes, i.e.
GET /candlein/owner/v2/
This would simply be:
@GET @Path("/v2") public Owner getOwnerNew(...)
With the v2 in front of the Resource we'll have to create a new set of resource classes.
jesus
On 04/27/2010 10:21 AM, Bryan Kearney wrote:
One of the backlog items talks about API versioning:
(E2) As an application integrator, I would like to define what version of the API I support in order to be protected from API changes.
The currenting thinking I am hearing is that you could use the media type for this, but it would be easier to just use the URL Path
/candlepin/some/resource candlepin/v2/some/resource
where no v implies v1.
If folks are comfortable with that, it would mean no work until we do v2. I would move this off the backlog unless there were concerns.
Comments?
-- bk _______________________________________________ candlepin mailing list candlepin@lists.fedorahosted.org https://fedorahosted.org/mailman/listinfo/candlepin
i think version in the url works and makes backwards-compatibility trivial. -d
On Tue, Apr 27, 2010 at 09:21:27AM -0400, Bryan Kearney wrote:
One of the backlog items talks about API versioning:
(E2) As an application integrator, I would like to define what version of the API I support in order to be protected from API changes.
The currenting thinking I am hearing is that you could use the media type for this, but it would be easier to just use the URL Path
/candlepin/some/resource candlepin/v2/some/resource
where no v implies v1.
If folks are comfortable with that, it would mean no work until we do v2. I would move this off the backlog unless there were concerns.
I like the URL but without the v
/candlepin/2.0/some/resource
+1 to url
jesus
On 04/27/2010 10:04 AM, Jesus Rodriguez wrote:
On Tue, Apr 27, 2010 at 09:21:27AM -0400, Bryan Kearney wrote:
One of the backlog items talks about API versioning:
(E2) As an application integrator, I would like to define what version of the API I support in order to be protected from API changes.
The currenting thinking I am hearing is that you could use the media type for this, but it would be easier to just use the URL Path
/candlepin/some/resource candlepin/v2/some/resource
where no v implies v1.
If folks are comfortable with that, it would mean no work until we do v2. I would move this off the backlog unless there were concerns.
I like the URL but without the v
/candlepin/2.0/some/resource
+1
But... the question is what makes something a new version of the api? Do we go full major.minor.micro and do the:
micro: bug fixes, nothing added or removed, no args or return values changed minor: new stuff added, optional args added, nothing removed major: might as well start over buckaroo!
Adrian
On Tue, Apr 27, 2010 at 10:36:11AM -0400, Adrian Likins wrote:
On 04/27/2010 10:04 AM, Jesus Rodriguez wrote:
On Tue, Apr 27, 2010 at 09:21:27AM -0400, Bryan Kearney wrote:
One of the backlog items talks about API versioning:
(E2) As an application integrator, I would like to define what version of the API I support in order to be protected from API changes.
The currenting thinking I am hearing is that you could use the media type for this, but it would be easier to just use the URL Path
/candlepin/some/resource candlepin/v2/some/resource
where no v implies v1.
If folks are comfortable with that, it would mean no work until we do v2. I would move this off the backlog unless there were concerns.
I like the URL but without the v
/candlepin/2.0/some/resource
+1
But... the question is what makes something a new version of the api? Do we go full major.minor.micro and do the:
micro: bug fixes, nothing added or removed, no args or return values changed minor: new stuff added, optional args added, nothing removed major: might as well start over buckaroo!
the 3 digit version is useful, smugmug.com does this. And the above definitions make sense.
jesus
On 04/27/2010 10:47 AM, Jesus Rodriguez wrote:
On Tue, Apr 27, 2010 at 10:36:11AM -0400, Adrian Likins wrote:
On 04/27/2010 10:04 AM, Jesus Rodriguez wrote:
On Tue, Apr 27, 2010 at 09:21:27AM -0400, Bryan Kearney wrote:
One of the backlog items talks about API versioning:
(E2) As an application integrator, I would like to define what version of the API I support in order to be protected from API changes.
The currenting thinking I am hearing is that you could use the media type for this, but it would be easier to just use the URL Path
/candlepin/some/resource candlepin/v2/some/resource
where no v implies v1.
If folks are comfortable with that, it would mean no work until we do v2. I would move this off the backlog unless there were concerns.
I like the URL but without the v
/candlepin/2.0/some/resource
+1
But... the question is what makes something a new version of the api? Do we go full major.minor.micro and do the:
micro: bug fixes, nothing added or removed, no args or return values changed minor: new stuff added, optional args added, nothing removed major: might as well start over buckaroo!
the 3 digit version is useful, smugmug.com does this. And the above definitions make sense.
jesus
I'm hoping that by the time we actually revisit this, we will come up with something better. The versioning scheme seems like it is in the wrong place.
It seems to me that the Version number is far more an element of the resource than an item in the URL path. Thus, I can see the argument for putting a version string into a document, and perhaps even requiring one for certain posts where the infomration is not complete unambiguous. But injecting it into the URL just sits wrong. I think this idea needs to lay fallow for a while, and only get implemented if we decide we really need it.
candlepin@lists.stg.fedorahosted.org
-
Adam Young -
Adrian Likins -
Bryan Kearney -
Devan Goodwin -
Dmitri Dolguikh -
James Bowes -
jesus rodriguez