Ah, sorry, I misunderstood. I thought when you said "a route that never
existed in 1.2 before" you meant e.g. /api/1.3/servers "didn't exist in
Golang or 1.3 before".
Right, for entirely new routes, e.g. deliveryservices/{xmlID}/urisignkeys,
path params are fine, and still conform to SemVer for the same major
version, e.g. 1.3.
On Wed, Apr 4, 2018 at 4:12 PM, Robert Butts <[email protected]>
wrote:
> You're right, in our code today, we don't use raw major versions
> (/api/1/foo) in our API, and our clients have hard-coded minor versions.
>
> If we feel like that's how we want to design APIs and clients, and say
> "our minor versions are not compatible with each-other", we can do that.
> But it's not Semantic Versioning.
>
> Semantic Versioning says: (semver.org)
> > MAJOR version when you make incompatible API changes,
> > MINOR version when you add functionality in a backwards-compatible manner
>
> Even if our current code doesn't strictly need SemVer, using a well-known
> standard makes it easier to understand. People know at a glance which
> versions are compatible, which have changed, and when they need to go read
> the docs again. Maybe someone else wants to write their own TO client, that
> expects SemVer.
>
> Is there a disadvantage to using SemVer? Even if we want to break
> backwards compatibility, we can just keep rolling major versions, /api/2/,
> /api/3/, /api/42/. I'd rather we didn't break compatibility so often, but
> if we do, there's no harm in the number itself.
>
>
> On Wed, Apr 4, 2018 at 4:00 PM, Volz, Dylan <[email protected]>
> wrote:
>
>> " a request from a client which is built to understand say /api/1.2/, if
>> that same request is made to /api/1.3/, it should still work."
>>
>> But this is a route that never existed in 1.2 before, not a new version
>> of a route in 1.3,
>> a client built to understand 1.2 will just not have this route at all and
>> would require
>> new dev work to support, or maybe I am misunderstanding you?
>>
>> On 4/4/18, 3:49 PM, "Robert Butts" <[email protected]> wrote:
>>
>> >Technically, adding new routes does not break old stuff right so i
>> don't
>> think that warrants a major version roll.
>>
>> New routes that use query params instead of path params will
>> definitely
>> break old stuff.
>>
>> When you say "break old stuff", the idea behind Semantic Versioning,
>> is
>> that a request from a client which is built to understand say
>> /api/1.2/, if
>> that same request is made to /api/1.3/, it should still work. If not,
>> it's
>> not Semantic Versioning.
>>
>> That also allows you to serve your latest minor version at /api/1/,
>> /api/2/, etc, and clients who know the Server is newer than them can
>> hit
>> the major endpoint, and be guaranteed to work. We don't currently do
>> that,
>> but it'd be nice if we did.
>>
>> I'm +1 on query params, but also +1 on https://semver.org/
>>
>>
>> On Wed, Apr 4, 2018 at 3:23 PM, Jeremy Mitchell <
>> [email protected]>
>> wrote:
>>
>> > tbh i'm not sure about versioning. I was just trying to suggest
>> that new
>> > routes be formulated this way per the new API guidelines:
>> >
>> > GET /foos[?id, name, etc=]
>> > POST /foos
>> > PUT /foos [?id, name, etc=]
>> > DELETE /foos [?id, name, etc=]
>> >
>> > instead of the old way:
>> >
>> > GET /foos
>> > GET /foos/:id
>> > POST /foos
>> > PUT /foos/:id
>> > DELETE /foos/:id
>> >
>> > The difference being the use of query params over route/path params.
>> >
>> > Technically, adding new routes does not break old stuff right so i
>> don't
>> > think that warrants a major version roll.
>> >
>> > While we're on the subject, what does everyone think if we took
>> this one
>> > step further and made routes handle a request payload with one or
>> more
>> > items. For example:
>> >
>> > GET /foos[?id, name, etc=]
>> > POST /foos <-- takes in an array of foos to create
>> > PUT /foos <-- takes in an array of foos to update
>> > DELETE /foos <-- takes in an array of foos to delete
>> >
>> > in this scenario, query params only pertain to the GET. The POST,
>> PUT and
>> > DELETE rely on the contents of the request json...
>> >
>> > Jeremy
>> >
>> >
>> >
>> >
>> >
>> >
>> >
>> >
>> >
>> >
>> >
>> > On Wed, Apr 4, 2018 at 1:55 PM, Robert Butts <
>> [email protected]>
>> > wrote:
>> >
>> > > That document doesn't mention versions, 1.2 vs 1.3 vs 2.0.
>> > >
>> > > Just to clarify, changing to query parameters breaks
>> compatibility with
>> > 1.2
>> > > and older, so new APIs in that format have to be a new major
>> version,
>> > i.e.
>> > > 2.0, per Semantic Versioning, right?
>> > >
>> > > On Tue, Apr 3, 2018 at 3:26 PM, Jeremy Mitchell <
>> [email protected]>
>> > > wrote:
>> > >
>> > > > FYI - I've updated the TO API guidelines to reflect our desire
>> to move
>> > > away
>> > > > from route/path params and embrace query params in the Golang
>> API.
>> > > >
>> > > > https://cwiki.apache.org/confluence/display/TC/API+Guidelines
>> > > >
>> > > > Jeremy
>> > > >
>> > >
>> >
>>
>>
>>
>
