Subject: [scim] API Versioning is too limiting?

From: Shelley <[email-masked]>
Date: Mon, 22 Jul 2013 11:52:13 -0500

We have implemented a variation of the SCIM API Versioning:

  https://{host}/{appName}/scim/{serviceProviderVersion}/{scimResource}

For example:

  https://company.com/roster/scim/v1/Users

The only difference is that we provide an *application-specific version *rather
than the *SCIM version*, and therefore consider the version to be part of
the "base URL" rather than the optional SCIM API Versioning portion of the
URL.

The use of a custom versioning strategy simply provides us with the
optional flexibility to version independently of SCIM if needed/desired.
While the general goal will be to limit or avoid non-passive changes, this
approach provides us with the flexibility to remove previously supported
functionality or attributes in new versions or to clarify/change behavior
if needed, while still hosting previous versions.

I understand the intent of the Schemas and ServiceProviderConfigs
endpoints, but in reality, our consumers are more likely to reference
external documentation rather than programmatically detecting changes in
the supported resources/protocol through these endpoints. Denoting major or
non-passive changes in the URL clarifies significant changes that consumers
must be aware of and also allows us to host multiple versions concurrently.

In practice, we may or may not ever need to deviate from the SCIM versions
in the future, but this approach allows us to do so. For example, the
initial release of our SCIM Service Provider is not yet fully
SCIM-compliant (there are a few features not required for our initial use
cases that we've omitted, for example), and so this allows us to use our
app-specific version rather than SCIM's v1 version.

---------- Forwarded message ----------
> From: Patrick Radtke <[email-masked]>
> To: Phil Hunt <[email-masked]>
> Cc: [email-masked]
> Date: Tue, 16 Jul 2013 14:11:02 -0700
> Subject: Re: [scim] API Versioning is too limiting?
> I don't think ServiceProviderConfigs would do what I had intended.
> Basically I wanted to run two incompatible versions of my (theoretical)
> SCIM 2 + extension based API at the same time, and allow clients to choose
> which one to use. Our normal way of doing that is using v1, v2, etc in the
> URL. Since that method is reserved by the SCIM spec, I'll probably use
> Accept headers to allow the client to distinguish which version to use, and
> then ( to avoid confusion ) not use the SCIM version in the url.
>
> -Patrick
>
> On 7/16/13 8:35 AM, Phil Hunt wrote:
>
>> My suggestion is using the ServerConfig resource to provide details about
>> extensions and options.
>>
>> Phil
>>
>> @independentid
>> www.independentid.com
>> [email-masked]
>>
>>
>>
>>
>>
>> On 2013-07-16, at 7:49 AM, Patrick Radtke <[email-masked]> wrote:
>>
>>
>>>  My understanding is this should be v2 since the simplecloud.info spec
>>>> is considered v1.
>>>>
>>>
>>> That makes sense.
>>>
>>>  Also the version should reflect the standard rev as opposed to
>>>> product rev of the implementation IMHO since interop expectations of
>>>> the client is the issue.
>>>>
>>>
>>> So how should product revisions be handled? Any service provider that
>>> makes use of SCIM's various extension points
>>> will want to rev their extensions independently of the main spec.
>>>
>>>
>>>> Suggest maybe we user /v2-01 for now and 02 for draft revision 2.
>>>> This will help implementers deal with breaking changes since many
>>>> are in prod now.
>>>>
>>>
>>> That makes sense to me, but I don't really have an opinion since I'm not
>>> in production with anything yet.
>>>
>>> -Patrick
>>>
>>>
>>> ______________________________**_________________
>>> scim mailing list
>>> [email-masked]
>>> https://www.ietf.org/mailman/**listinfo/scim<https://www.ietf.org/mailman/listinfo/scim>
>>>
>>
>>
>
>
>
> ---------- Forwarded message ----------
> From: Phil Hunt <[email-masked]>
> To: Patrick Radtke <[email-masked]>
> Cc: "[email-masked]" <[email-masked]>
> Date: Tue, 16 Jul 2013 14:34:16 -0700
> Subject: Re: [scim] API Versioning is too limiting?
> If they are incompatible what aspect is the nature of uncompatability?
>
>   Extensions that are data extensions, do not impact the protocol and this
> the version shouldn't change. .
>
> Maybe you need different endpoints?
>
> Phil
>
> On 2013-07-16, at 14:11, Patrick Radtke <[email-masked]> wrote:
>
> > I don't think ServiceProviderConfigs would do what I had intended.
> > Basically I wanted to run two incompatible versions of my (theoretical)
> SCIM 2 + extension based API at the same time, and allow clients to choose
> which one to use. Our normal way of doing that is using v1, v2, etc in the
> URL. Since that method is reserved by the SCIM spec, I'll probably use
> Accept headers to allow the client to distinguish which version to use, and
> then ( to avoid confusion ) not use the SCIM version in the url.
> >
> > -Patrick
> >
> > On 7/16/13 8:35 AM, Phil Hunt wrote:
> >> My suggestion is using the ServerConfig resource to provide details
> about extensions and options.
> >>
> >> Phil
> >>
> >> @independentid
> >> www.independentid.com
> >> [email-masked]
> >>
> >>
> >>
> >>
> >>
> >> On 2013-07-16, at 7:49 AM, Patrick Radtke <[email-masked]> wrote:
> >>
> >>>
> >>>> My understanding is this should be v2 since the simplecloud.info spec
> >>>> is considered v1.
> >>>
> >>> That makes sense.
> >>>
> >>>> Also the version should reflect the standard rev as opposed to
> >>>> product rev of the implementation IMHO since interop expectations of
> >>>> the client is the issue.
> >>>
> >>> So how should product revisions be handled? Any service provider that
> makes use of SCIM's various extension points
> >>> will want to rev their extensions independently of the main spec.
> >>>
> >>>>
> >>>> Suggest maybe we user /v2-01 for now and 02 for draft revision 2.
> >>>> This will help implementers deal with breaking changes since many
> >>>> are in prod now.
> >>>
> >>> That makes sense to me, but I don't really have an opinion since I'm
> not in production with anything yet.
> >>>
> >>> -Patrick
> >>>
> >>>
> >>> _______________________________________________
> >>> scim mailing list
> >>> [email-masked]
> >>> https://www.ietf.org/mailman/listinfo/scim
> >
> > _______________________________________________
> > scim mailing list
> > [email-masked]
> > https://www.ietf.org/mailman/listinfo/scim
>
>
>
> ---------- Forwarded message ----------
> From: Patrick Radtke <[email-masked]>
> To: Phil Hunt <[email-masked]>
> Cc: "[email-masked]" <[email-masked]>
> Date: Tue, 16 Jul 2013 15:23:49 -0700
> Subject: Re: [scim] API Versioning is too limiting?
> Let say in rev A of my API I added a filter operation for "sounds likes"
> and I call it 'sl'
>
> A campus vendor provides clients on iPhones used by thousands of students
> and it uses that filter for doing searches
>
> GET /vA/Users?filter=name.**familyName sl "smith"
>
> For some reason (performance, compatibility, hosting cost, etc) we want to
> deprecate and remove that filter in rev B of our SCIM based API, but until
> we can update the clients we want to run both versions.
> Normally I would do what you suggest with the different endpoints, and I
> would use v# to distinguish those endpoints. I can of course still use
> something else to distinguish those endpoints (e.g /revB/Users). I guess I
> was just surprised after reading the API versioning section to see my
> preferred method removed from my control, and I didn't initially understand
> why.
>
> Anyhow, I don't have real life examples of this. I'm still planning out
> how we'll use SCIM.
>
> Phil, thanks for helping me clarify my understanding of this.
>
> -Patrick
>
>
>
>
>
>
>
> On 7/16/13 2:34 PM, Phil Hunt wrote:
>
>> If they are incompatible what aspect is the nature of uncompatability?
>>
>>    Extensions that are data extensions, do not impact the protocol and
>> this the version shouldn't change. .
>>
>> Maybe you need different endpoints?
>>
>> Phil
>>
>> On 2013-07-16, at 14:11, Patrick Radtke <[email-masked]> wrote:
>>
>>  I don't think ServiceProviderConfigs would do what I had intended.
>>> Basically I wanted to run two incompatible versions of my (theoretical)
>>> SCIM 2 + extension based API at the same time, and allow clients to choose
>>> which one to use. Our normal way of doing that is using v1, v2, etc in the
>>> URL. Since that method is reserved by the SCIM spec, I'll probably use
>>> Accept headers to allow the client to distinguish which version to use, and
>>> then ( to avoid confusion ) not use the SCIM version in the url.
>>>
>>> -Patrick
>>>
>>> On 7/16/13 8:35 AM, Phil Hunt wrote:
>>>
>>>> My suggestion is using the ServerConfig resource to provide details
>>>> about extensions and options.
>>>>
>>>> Phil
>>>>
>>>> @independentid
>>>> www.independentid.com
>>>> [email-masked]
>>>>
>>>>
>>>>
>>>>
>>>>
>>>> On 2013-07-16, at 7:49 AM, Patrick Radtke <[email-masked]> wrote:
>>>>
>>>>
>>>>>  My understanding is this should be v2 since the simplecloud.info spec
>>>>>> is considered v1.
>>>>>>
>>>>>
>>>>> That makes sense.
>>>>>
>>>>>  Also the version should reflect the standard rev as opposed to
>>>>>> product rev of the implementation IMHO since interop expectations of
>>>>>> the client is the issue.
>>>>>>
>>>>>
>>>>> So how should product revisions be handled? Any service provider that
>>>>> makes use of SCIM's various extension points
>>>>> will want to rev their extensions independently of the main spec.
>>>>>
>>>>>
>>>>>> Suggest maybe we user /v2-01 for now and 02 for draft revision 2.
>>>>>> This will help implementers deal with breaking changes since many
>>>>>> are in prod now.
>>>>>>
>>>>>
>>>>> That makes sense to me, but I don't really have an opinion since I'm
>>>>> not in production with anything yet.
>>>>>
>>>>> -Patrick
>>>>>
>>>>>
>>>>> ______________________________**_________________
>>>>> scim mailing list
>>>>> [email-masked]
>>>>> https://www.ietf.org/mailman/**listinfo/scim<https://www.ietf.org/mailman/listinfo/scim>
>>>>>
>>>>
>>> ______________________________**_________________
>>> scim mailing list
>>> [email-masked]
>>> https://www.ietf.org/mailman/**listinfo/scim<https://www.ietf.org/mailman/listinfo/scim>
>>>
>>
>
>
> _______________________________________________
> scim mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/scim
>
>

---

From: Phil Hunt <[email-masked]>
Date: Mon, 22 Jul 2013 10:39:36 -0700

Hmm. The schema is the configurable part. The api is the protocol. 

So sp's setting version number based on schema seems like a big problem for clients trying to figure what protocol version to speak. Eg how does this sp expect the patch command to be formatted?

Phil

On 2013-07-22, at 9:52, Shelley <[email-masked]> wrote:

> The only difference is that we provide an application-specific version rather than the SCIM version, and therefore consider the version to be part of the "base URL" rather than the optional SCIM API Versioning portion of the URL.
> 
> The use of a custom versioning strategy simply provides us with the optional flexibility to version independently of SCIM if needed/desired. While the general goal will be to limit or avoid non-passive changes, this approach provides us with the flexibility to remove previously supported functionality or attributes in new versions or to clarify/change behavior if needed, while still hosting previous versions.
> 
> I understand the intent of the Schemas and ServiceProviderConfigs  endpoints, but in reality, our consumers are more likely to reference external documentation rather than programmatically detecting changes in the supported resources/protocol through these endpoints. Denoting major or non-passive changes in the URL clarifies significant changes that consumers must be aware of and also allows us to host multiple versions concurrently.
> 
> In practice, we may or may not ever need to deviate from the SCIM versions in the future, but this approach allows us to do so. For example, the initial release of our SCIM Service Provider is not yet fully SCIM-compliant (there are a few features not required for our initial use cases that we've omitted, for example), and so this allows us to use our app-specific version rather than SCIM's v1 version.
> 
> 
>> Basically I wanted to run two incompatible versions of my (theoretical) SCIM 2 + extension based API at the same time, and allow clients to choose which one to use. Our normal way of doing that is using v1, v2, etc in the URL. Since that method is reserved by the SCIM spec, I'll probably use Accept headers to allow the client to distinguish which version to use, and then ( to avoid confusion ) not use the SCIM version in the url.
>> 
>> -Patrick
>> 
>>> My suggestion is using the ServerConfig resource to provide details about extensions and options.
>>> 
>>> Phil
>>> 
>>> @independentid
>>> www.independentid.com
>>> [email-masked]
>>> 
>>> 
>>> 
>>> 
>>> 
>>>> So how should product revisions be handled? Any service provider that makes use of SCIM's various extension points
>>>> That makes sense to me, but I don't really have an opinion since I'm not in production with anything yet.
>>>> 
>>>> -Patrick
>>>> 
>>>> 
>>   Extensions that are data extensions, do not impact the protocol and this the version shouldn't change. .
>> 
>> > Basically I wanted to run two incompatible versions of my (theoretical) SCIM 2 + extension based API at the same time, and allow clients to choose which one to use. Our normal way of doing that is using v1, v2, etc in the URL. Since that method is reserved by the SCIM spec, I'll probably use Accept headers to allow the client to distinguish which version to use, and then ( to avoid confusion ) not use the SCIM version in the url.
>> >
>> > -Patrick
>> >
>> >> My suggestion is using the ServerConfig resource to provide details about extensions and options.
>> >>
>> >> Phil
>> >>
>> >> @independentid
>> >> www.independentid.com
>> >> [email-masked]
>> >>
>> >>
>> >>
>> >>
>> >>
>> >>> So how should product revisions be handled? Any service provider that makes use of SCIM's various extension points
>> >>> That makes sense to me, but I don't really have an opinion since I'm not in production with anything yet.
>> >>>
>> >>> -Patrick
>> >>>
>> >>>
>> Let say in rev A of my API I added a filter operation for "sounds likes" and I call it 'sl'
>> 
>> A campus vendor provides clients on iPhones used by thousands of students and it uses that filter for doing searches
>> 
>> GET /vA/Users?filter=name.familyName sl "smith"
>> 
>> For some reason (performance, compatibility, hosting cost, etc) we want to deprecate and remove that filter in rev B of our SCIM based API, but until we can update the clients we want to run both versions.
>> Normally I would do what you suggest with the different endpoints, and I would use v# to distinguish those endpoints. I can of course still use something else to distinguish those endpoints (e.g /revB/Users). I guess I was just surprised after reading the API versioning section to see my preferred method removed from my control, and I didn't initially understand why.
>> 
>> Anyhow, I don't have real life examples of this. I'm still planning out how we'll use SCIM.
>> 
>>>    Extensions that are data extensions, do not impact the protocol and this the version shouldn't change. .
>>> 
>>>> Basically I wanted to run two incompatible versions of my (theoretical) SCIM 2 + extension based API at the same time, and allow clients to choose which one to use. Our normal way of doing that is using v1, v2, etc in the URL. Since that method is reserved by the SCIM spec, I'll probably use Accept headers to allow the client to distinguish which version to use, and then ( to avoid confusion ) not use the SCIM version in the url.
>>>> 
>>>> -Patrick
>>>> 
>>>>> My suggestion is using the ServerConfig resource to provide details about extensions and options.
>>>>> 
>>>>> Phil
>>>>> 
>>>>> @independentid
>>>>> www.independentid.com
>>>>> [email-masked]
>>>>> 
>>>>> 
>>>>> 
>>>>> 
>>>>> 
>>>>>> So how should product revisions be handled? Any service provider that makes use of SCIM's various extension points
>>>>>> That makes sense to me, but I don't really have an opinion since I'm not in production with anything yet.
>>>>>> 
>>>>>> -Patrick
>>>>>> 
>>>>>>

---

From: Phil Hunt <[email-masked]>
Date: Mon, 22 Jul 2013 11:50:47 -0700

Another thought. What if products could have a product version alias?

Eg

/pXYZ/Users
/v2/Users

One might be the same as the other if pXYZ is an implementation if v2. 

However client would have to go to product site to know what differences are or what superset of func is implied. 

IOW /vNNN implies some expectation of interop based on ietf specs without having to know what implementation or product implements it. 

Phil

---

From: Shelley <[email-masked]>
Date: Mon, 22 Jul 2013 14:19:01 -0500

Consumers already refer to external documentation first, and are more
likely to utilize that doc than to attempt to programmatically determine
supported resources and vary functionality. The SP version would document
which SCIM version it supports.

Also, since API versioning is already only optional per the SCIM spec, this
same question may be more relevant to SPs that don't implement API
versioning at all. Also, how is a consumer to discover which version(s) of
SCIM an SP supports?

On Mon, Jul 22, 2013 at 12:39 PM, Phil Hunt <[email-masked]> wrote:

> So sp's setting version number based on schema seems like a big problem
> for clients trying to figure what protocol version to speak. Eg how does
> this sp expect the patch command to be formatted?
>
> Phil
>
>> >>>> My understanding is this should be v2 since the simplecloud.infospec
>> >>>> is considered v1.
>> >>>
>> >>> That makes sense.
>> >>>
>> For some reason (performance, compatibility, hosting cost, etc) we want
>> to deprecate and remove that filter in rev B of our SCIM based API, but
>> until we can update the clients we want to run both versions.
>>>>>>  My understanding is this should be v2 since the simplecloud.infospec
>>>>>>> is considered v1.
>>>>>>>
>>>>>>
>>>>>> That makes sense.
>>>>>>