Subject: [scim] API Versioning is too limiting?

From: Patrick Radtke <[email-masked]>
Date: Mon, 15 Jul 2013 17:18:24 -0700

According to 3.10 API Versioning
http://tools.ietf.org/id/draft-ietf-scim-api-01.html#rfc.section.3.10

If I want to include an API version in my url then the only option, and 
accepted value is 'v1'. A version User resource would be located at
/v1/Users/2819c223-7f76-453a-919d-413861904646

This seems too limiting. The spec mandates a value of 'v1', however the 
service provider likely wants to use the versioning to indicate the 
version of their API, not the version of SCIM. A service provider can 
add additional schemas or filter operations on top of the standard 
schema. If the service provider then decides to make non-backwards 
compatible changes in their own extensions, how are they suppose to 
version their API?

A more concrete example.
Example.com release v1 of their api, and they add a custom schema to 
user. This schema adds an attribute called 'exampleComLevel'

GET /v1/Users/2819c223-7f76-453a-919d-413861904646

HTTP/1.1 200 OK

{
   "schemas":["urn:scim:schemas:core:1.0", 
"urn:scim:schemas:extension:example:1.0"],
   "id":"2819c223-7f76-453a-919d-413861904646,
   "userName":"bjensen",
   "exampleComLevel": "gold"
}

Later, they decide that 'exampleComLevel' should be an array. They 
release a new 2.0 schema and want to version their API so that

GET /v2/Users/2819c223-7f76-453a-919d-413861904646

returns

HTTP/1.1 200 OK

{
   "schemas":["urn:scim:schemas:core:1.0", 
"urn:scim:schemas:extension:example:2.0"],
   "id":"2819c223-7f76-453a-919d-413861904646,
   "userName":"bjensen",
   "exampleComLevel": ["gold","elite"]
}

Service consumers can then upgrade to the new API version as needed.

thanks,

Patrick

---

From: Phil Hunt <[email-masked]>
Date: Mon, 15 Jul 2013 18:52:46 -0700

My understanding is this should be v2 since the simplecloud.info spec is considered v1. 

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. 

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. 

Phil

On 2013-07-15, at 17:18, Patrick Radtke <[email-masked]> wrote:

> If I want to include an API version in my url then the only option, and accepted value is 'v1'. A version User resource would be located at
> This seems too limiting. The spec mandates a value of 'v1', however the service provider likely wants to use the versioning to indicate the version of their API, not the version of SCIM. A service provider can add additional schemas or filter operations on top of the standard schema. If the service provider then decides to make non-backwards compatible changes in their own extensions, how are they suppose to version their API?
> 
> A more concrete example.
> Example.com release v1 of their api, and they add a custom schema to user. This schema adds an attribute called 'exampleComLevel'
> 
>  "schemas":["urn:scim:schemas:core:1.0", "urn:scim:schemas:extension:example:1.0"],
> Later, they decide that 'exampleComLevel' should be an array. They release a new 2.0 schema and want to version their API so that
> 
>  "schemas":["urn:scim:schemas:core:1.0", "urn:scim:schemas:extension:example:2.0"],
> _______________________________________________
> scim mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/scim

---

From: Patrick Radtke <[email-masked]>
Date: Tue, 16 Jul 2013 07:49:27 -0700 (PDT)

> My understanding is this should be v2 since the simplecloud.info spec

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

---

From: Phil Hunt <[email-masked]>
Date: Tue, 16 Jul 2013 08:35:30 -0700

My suggestion is using the ServerConfig resource to provide details about extensions and options.

Phil

@independentid
www.independentid.com
[email-masked]

---

From: Patrick Radtke <[email-masked]>
Date: Tue, 16 Jul 2013 14:11:02 -0700

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

---

From: Phil Hunt <[email-masked]>
Date: Tue, 16 Jul 2013 14:34:16 -0700

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:

> 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
>

---

From: Patrick Radtke <[email-masked]>
Date: Tue, 16 Jul 2013 15:23:49 -0700

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