API Operation Version Confusion
|
|
Bruce Dechant
|
Hi All,
I would like to discuss the confusion on the API version information. Currently, all of the APIs have an associated operation "VERSION". This "VERSION" hasn't been clearly defined and after looking at the latest code base we are using it inconsistently throughout the project. Examples: TestConnection - Operation version 1.0.0 - MGOS Release 1.0 - EnumerateUnmanagedData - Operation version 1.0.0 - MGOS Release 1.2 DescribeSchema - Operation version 1.0.0 - MGOS Release 1.0, but in MGOS Release 2.1 a new 3 parameter API signature was added along with keeping the old 2 parameter version GetTile - Operation version 1.2.0 - MGOS Release 1.2 RenderDynamicOverlay - Operation version 2.1.0 - MGOS Release 1.0, but in MGOS Release 2.1 a new API signature was added along with keeping the old versions >From the above examples it is not clear what operation "VERSION" naming scheme to use. - Is the operation "VERSION" for new APIs set to 1.0.0? - Or is the operation "VERSION" equal to the version of the MGOS Release? - What about APIs that have had only a signature change? What to use in this case? As you can see we have not been following a well defined operation "VERSION" scheme and this is something we need to correct as it is confusing. I would like to hear from the community on what they would like to see going forward as I would like to clear up the confusion :) Thanks, Bruce _______________________________________________ mapguide-internals mailing list [hidden email] http://lists.osgeo.org/mailman/listinfo/mapguide-internals |
||||||||||||||||
Dave Wilson
|
I'm not sure what the standard for this in open source, but logically the version reflects the version the API was introduced in or updated in. If it hasn't been updated the version wouldn't change. This would act like a label so that you can find all the 1.0.0 APIs, the 1.2.1 APIs (or revisions) and so on. That would seem like useful information to me. If an API doesn't have a 1.0.0 version you know it was introduced later.
My 2 cents. Dave -----Original Message----- From: [hidden email] [mailto:[hidden email]] On Behalf Of Bruce Dechant Sent: Monday, August 17, 2009 1:51 PM To: MapGuide Internals Mail List Subject: [mapguide-internals] API Operation Version Confusion Hi All, I would like to discuss the confusion on the API version information. Currently, all of the APIs have an associated operation "VERSION". This "VERSION" hasn't been clearly defined and after looking at the latest code base we are using it inconsistently throughout the project. Examples: TestConnection - Operation version 1.0.0 - MGOS Release 1.0 - EnumerateUnmanagedData - Operation version 1.0.0 - MGOS Release 1.2 DescribeSchema - Operation version 1.0.0 - MGOS Release 1.0, but in MGOS Release 2.1 a new 3 parameter API signature was added along with keeping the old 2 parameter version GetTile - Operation version 1.2.0 - MGOS Release 1.2 RenderDynamicOverlay - Operation version 2.1.0 - MGOS Release 1.0, but in MGOS Release 2.1 a new API signature was added along with keeping the old versions >From the above examples it is not clear what operation "VERSION" naming scheme to use. - Is the operation "VERSION" for new APIs set to 1.0.0? - Or is the operation "VERSION" equal to the version of the MGOS Release? - What about APIs that have had only a signature change? What to use in this case? As you can see we have not been following a well defined operation "VERSION" scheme and this is something we need to correct as it is confusing. I would like to hear from the community on what they would like to see going forward as I would like to clear up the confusion :) Thanks, Bruce _______________________________________________ mapguide-internals mailing list [hidden email] http://lists.osgeo.org/mailman/listinfo/mapguide-internals _______________________________________________ mapguide-internals mailing list [hidden email] http://lists.osgeo.org/mailman/listinfo/mapguide-internals |
||||||||||||||||
Jason Birch
|
That makes sense to me too. Using the web api version rather than a function-specific revision adds a lot of value.
I guess my question though is, how do we move to consolidate on this system without causing backwards compatibility issues? Is it too late to standardise on this system and gain value from it? Jason -----Original Message----- From: Dave Wilson Sent: Monday, August 17, 2009 1:01 PM To: MapGuide Internals Mail List Subject: [mapguide-internals] RE: API Operation Version Confusion I'm not sure what the standard for this in open source, but logically the version reflects the version the API was introduced in or updated in. If it hasn't been updated the version wouldn't change. This would act like a label so that you can find all the 1.0.0 APIs, the 1.2.1 APIs (or revisions) and so on. That would seem like useful information to me. If an API doesn't have a 1.0.0 version you know it was introduced later. -----Original Message----- From: Bruce Dechant Sent: Monday, August 17, 2009 1:51 PM To: MapGuide Internals Mail List Subject: [mapguide-internals] API Operation Version Confusion I would like to discuss the confusion on the API version information. Currently, all of the APIs have an associated operation "VERSION". This "VERSION" hasn't been clearly defined and after looking at the latest code base we are using it inconsistently throughout the project. As you can see we have not been following a well defined operation "VERSION" scheme and this is something we need to correct as it is confusing. _______________________________________________ mapguide-internals mailing list [hidden email] http://lists.osgeo.org/mailman/listinfo/mapguide-internals |
||||||||||||||||
Trevor Wekel
|
I think using the MGOS version for any changed or new operation makes it clear as to which version of MGOS the operation is compatible with.
In some cases, like DescribeSchema, it looks as though we have been a bit lazy with the convention. Even if the signature is backward compatible, we should probably revision it so developers (and the community) know where the API is applicable. Thanks Bruce and Dave for pointing out the inconsistencies and helping to explain why it makes sense to revision the operations. As Jason mentioned, I do not think we can change any of the broken APIs since they have already been released. However, we should stick to the chosen convention for future releases. I would vote for HTTP API version = version of MGOS where API was introduced or changed. Thanks, Trevor -----Original Message----- From: [hidden email] [mailto:[hidden email]] On Behalf Of Jason Birch Sent: August 17, 2009 2:06 PM To: MapGuide Internals Mail List Subject: [mapguide-internals] RE: API Operation Version Confusion That makes sense to me too. Using the web api version rather than a function-specific revision adds a lot of value. I guess my question though is, how do we move to consolidate on this system without causing backwards compatibility issues? Is it too late to standardise on this system and gain value from it? Jason -----Original Message----- From: Dave Wilson Sent: Monday, August 17, 2009 1:01 PM To: MapGuide Internals Mail List Subject: [mapguide-internals] RE: API Operation Version Confusion I'm not sure what the standard for this in open source, but logically the version reflects the version the API was introduced in or updated in. If it hasn't been updated the version wouldn't change. This would act like a label so that you can find all the 1.0.0 APIs, the 1.2.1 APIs (or revisions) and so on. That would seem like useful information to me. If an API doesn't have a 1.0.0 version you know it was introduced later. -----Original Message----- From: Bruce Dechant Sent: Monday, August 17, 2009 1:51 PM To: MapGuide Internals Mail List Subject: [mapguide-internals] API Operation Version Confusion I would like to discuss the confusion on the API version information. Currently, all of the APIs have an associated operation "VERSION". This "VERSION" hasn't been clearly defined and after looking at the latest code base we are using it inconsistently throughout the project. As you can see we have not been following a well defined operation "VERSION" scheme and this is something we need to correct as it is confusing. _______________________________________________ mapguide-internals mailing list [hidden email] http://lists.osgeo.org/mailman/listinfo/mapguide-internals _______________________________________________ mapguide-internals mailing list [hidden email] http://lists.osgeo.org/mailman/listinfo/mapguide-internals |
||||||||||||||||
|
Bruce Dechant
|
The good news is that there are only a handful of APIs that are broken with either versioning scheme.
So I don't think it is too late to correct this. For backwards compatibility it would be safer to leave the broken ones as is and just apply the chosen versioning scheme moving forward. Once the versioning scheme is chosen I will be happy to document this on the MapGuide site along with which APIs are not following the scheme. Thanks, Bruce -----Original Message----- From: [hidden email] [mailto:[hidden email]] On Behalf Of Trevor Wekel Sent: Monday, August 17, 2009 3:02 PM To: MapGuide Internals Mail List Subject: [mapguide-internals] RE: API Operation Version Confusion I think using the MGOS version for any changed or new operation makes it clear as to which version of MGOS the operation is compatible with. In some cases, like DescribeSchema, it looks as though we have been a bit lazy with the convention. Even if the signature is backward compatible, we should probably revision it so developers (and the community) know where the API is applicable. Thanks Bruce and Dave for pointing out the inconsistencies and helping to explain why it makes sense to revision the operations. As Jason mentioned, I do not think we can change any of the broken APIs since they have already been released. However, we should stick to the chosen convention for future releases. I would vote for HTTP API version = version of MGOS where API was introduced or changed. Thanks, Trevor -----Original Message----- From: [hidden email] [mailto:[hidden email]] On Behalf Of Jason Birch Sent: August 17, 2009 2:06 PM To: MapGuide Internals Mail List Subject: [mapguide-internals] RE: API Operation Version Confusion That makes sense to me too. Using the web api version rather than a function-specific revision adds a lot of value. I guess my question though is, how do we move to consolidate on this system without causing backwards compatibility issues? Is it too late to standardise on this system and gain value from it? Jason -----Original Message----- From: Dave Wilson Sent: Monday, August 17, 2009 1:01 PM To: MapGuide Internals Mail List Subject: [mapguide-internals] RE: API Operation Version Confusion I'm not sure what the standard for this in open source, but logically the version reflects the version the API was introduced in or updated in. If it hasn't been updated the version wouldn't change. This would act like a label so that you can find all the 1.0.0 APIs, the 1.2.1 APIs (or revisions) and so on. That would seem like useful information to me. If an API doesn't have a 1.0.0 version you know it was introduced later. -----Original Message----- From: Bruce Dechant Sent: Monday, August 17, 2009 1:51 PM To: MapGuide Internals Mail List Subject: [mapguide-internals] API Operation Version Confusion I would like to discuss the confusion on the API version information. Currently, all of the APIs have an associated operation "VERSION". This "VERSION" hasn't been clearly defined and after looking at the latest code base we are using it inconsistently throughout the project. As you can see we have not been following a well defined operation "VERSION" scheme and this is something we need to correct as it is confusing. _______________________________________________ mapguide-internals mailing list [hidden email] http://lists.osgeo.org/mailman/listinfo/mapguide-internals _______________________________________________ mapguide-internals mailing list [hidden email] http://lists.osgeo.org/mailman/listinfo/mapguide-internals _______________________________________________ mapguide-internals mailing list [hidden email] http://lists.osgeo.org/mailman/listinfo/mapguide-internals |
||||||||||||||||
Tom Fukushima
|
In reply to this post
by Jason Birch
The only thing I could see as a benefit to the 1.0.0 approach is that you always know there is a 1.0.0 version of the particular API you are using. This could help you quickly rule out that filling in the wrong version number is the thing that is causing the request to fail (putting in an unknown version number like 1.0.0 *will* cause the request to fail)---other than that I don't know of any reason to use it; and I personally *don't* believe that this is a strong reason to use it.
What value does syncing with the web API version add? I can see that if you write a MapGuide application you may be able to figure out which version of the web tier is required if you look for "VERSION=" strings. I'm not sure how useful this is or how accurate it would be though. Anything else? Is it a downside that we cannot extend APIs without revving the version? I don't think that this is a negative; as Trevor says, we should not be lazy and always rev the version for any change. We would need to see what the use of this is before we decide how much backwards incompatibility we introduce. Give the above reasons I don't think that they are strong enough to make us break compatibility. I would like to hear concrete reasons from application developers on which they would prefer. Ultimately, we want to cater to them. Choosing one or the other doesn't matter for the core developers. Tom -----Original Message----- From: [hidden email] [mailto:[hidden email]] On Behalf Of Jason Birch Sent: Monday, August 17, 2009 2:06 PM To: MapGuide Internals Mail List Subject: [mapguide-internals] RE: API Operation Version Confusion That makes sense to me too. Using the web api version rather than a function-specific revision adds a lot of value. I guess my question though is, how do we move to consolidate on this system without causing backwards compatibility issues? Is it too late to standardise on this system and gain value from it? Jason -----Original Message----- From: Dave Wilson Sent: Monday, August 17, 2009 1:01 PM To: MapGuide Internals Mail List Subject: [mapguide-internals] RE: API Operation Version Confusion I'm not sure what the standard for this in open source, but logically the version reflects the version the API was introduced in or updated in. If it hasn't been updated the version wouldn't change. This would act like a label so that you can find all the 1.0.0 APIs, the 1.2.1 APIs (or revisions) and so on. That would seem like useful information to me. If an API doesn't have a 1.0.0 version you know it was introduced later. -----Original Message----- From: Bruce Dechant Sent: Monday, August 17, 2009 1:51 PM To: MapGuide Internals Mail List Subject: [mapguide-internals] API Operation Version Confusion I would like to discuss the confusion on the API version information. Currently, all of the APIs have an associated operation "VERSION". This "VERSION" hasn't been clearly defined and after looking at the latest code base we are using it inconsistently throughout the project. As you can see we have not been following a well defined operation "VERSION" scheme and this is something we need to correct as it is confusing. _______________________________________________ mapguide-internals mailing list [hidden email] http://lists.osgeo.org/mailman/listinfo/mapguide-internals _______________________________________________ mapguide-internals mailing list [hidden email] http://lists.osgeo.org/mailman/listinfo/mapguide-internals |
||||||||||||||||
|
Tom Fukushima
|
BTW, our XML schemas are API as well. We should consider how to version them as well. The all currently follow the 1.0.0 scheme.
-----Original Message----- From: [hidden email] [mailto:[hidden email]] On Behalf Of Tom Fukushima Sent: Monday, August 17, 2009 3:18 PM To: MapGuide Internals Mail List Subject: [mapguide-internals] RE: API Operation Version Confusion The only thing I could see as a benefit to the 1.0.0 approach is that you always know there is a 1.0.0 version of the particular API you are using. This could help you quickly rule out that filling in the wrong version number is the thing that is causing the request to fail (putting in an unknown version number like 1.0.0 *will* cause the request to fail)---other than that I don't know of any reason to use it; and I personally *don't* believe that this is a strong reason to use it. What value does syncing with the web API version add? I can see that if you write a MapGuide application you may be able to figure out which version of the web tier is required if you look for "VERSION=" strings. I'm not sure how useful this is or how accurate it would be though. Anything else? Is it a downside that we cannot extend APIs without revving the version? I don't think that this is a negative; as Trevor says, we should not be lazy and always rev the version for any change. We would need to see what the use of this is before we decide how much backwards incompatibility we introduce. Give the above reasons I don't think that they are strong enough to make us break compatibility. I would like to hear concrete reasons from application developers on which they would prefer. Ultimately, we want to cater to them. Choosing one or the other doesn't matter for the core developers. Tom -----Original Message----- From: [hidden email] [mailto:[hidden email]] On Behalf Of Jason Birch Sent: Monday, August 17, 2009 2:06 PM To: MapGuide Internals Mail List Subject: [mapguide-internals] RE: API Operation Version Confusion That makes sense to me too. Using the web api version rather than a function-specific revision adds a lot of value. I guess my question though is, how do we move to consolidate on this system without causing backwards compatibility issues? Is it too late to standardise on this system and gain value from it? Jason -----Original Message----- From: Dave Wilson Sent: Monday, August 17, 2009 1:01 PM To: MapGuide Internals Mail List Subject: [mapguide-internals] RE: API Operation Version Confusion I'm not sure what the standard for this in open source, but logically the version reflects the version the API was introduced in or updated in. If it hasn't been updated the version wouldn't change. This would act like a label so that you can find all the 1.0.0 APIs, the 1.2.1 APIs (or revisions) and so on. That would seem like useful information to me. If an API doesn't have a 1.0.0 version you know it was introduced later. -----Original Message----- From: Bruce Dechant Sent: Monday, August 17, 2009 1:51 PM To: MapGuide Internals Mail List Subject: [mapguide-internals] API Operation Version Confusion I would like to discuss the confusion on the API version information. Currently, all of the APIs have an associated operation "VERSION". This "VERSION" hasn't been clearly defined and after looking at the latest code base we are using it inconsistently throughout the project. As you can see we have not been following a well defined operation "VERSION" scheme and this is something we need to correct as it is confusing. _______________________________________________ mapguide-internals mailing list [hidden email] http://lists.osgeo.org/mailman/listinfo/mapguide-internals _______________________________________________ mapguide-internals mailing list [hidden email] http://lists.osgeo.org/mailman/listinfo/mapguide-internals _______________________________________________ mapguide-internals mailing list [hidden email] http://lists.osgeo.org/mailman/listinfo/mapguide-internals |
||||||||||||||||
| Free Embeddable Forum Powered by Nabble | Help |
