Subject: [scim] Questions regarding SCIM endpoints and other extended Resources in SCIM

From: Shivang Shah <[email-masked]>
Date: Tue, 10 Dec 2013 16:45:18 -0800

Hi Everyone,

(Apologize if this is double posting ! I posted previously before I was
subscribed to the listing!)

I had couple of questions regarding the SCIM api endpoints discussed here :
http://www.simplecloud.info/specs/draft-scim-api-01.html and I thought this
might be a good place to start with.

In the specs I see the following :

"The SCIM protocol specifies well known endpoints and HTTP methods for
managing Resources defined in the core schema; i.e., User and Group
Resources correspond to /Users and /Groups respectively. Service Providers
that support extended Resources SHOULD define Resource endpoints using the
established convention; pluralize the Resource name defined in the extended
schema by appending an 's'. Given there are cases where Resource
pluralization is ambiguous; e.g., a Resource named 'person' is legitimately
'persons' and 'people' Consumers SHOULD discover Resource endpoints via the
Schema Sub-Attribute 'endpoint'. "

What I don't understand is the following:

1) I have never seen Capitalization of the Resource name before. Is this
something new for SCIM? Urls in browsers (urls anywhere for that matter)
are by default case insensitive and it doesn't matter if we capitalize it
or not. My real question would be is capitalizing the Resource name a part
of the spec or just an example?
2) (This might be bit more of a mesh up question between REST spec and
SCIM). We have a scenario where a user HAS "favorites". There are 2 ways we
can handle this:

/scim/v1/users/{userId}/favorites (we can call this an extended
sub-resource)

OR

/scim/favorites/users/{userId} (we can all this an extended resource
"favorites").

>From the url perspective both seem to be right but what I don't know is
which one is more suitable according to SCIM (and maybe REST? )
specifications. And a follow up question to that might be, do the extended
resources have to be capitalized as well?

All help is appreciated! I am new to implementing and understanding SCIM,
so please forgive me if I have missed some subtle pointers in the
specifications itself!

Cheers and looking forward to any answers that can help me understand this!

---

From: Shivang Shah <[email-masked]>
Date: Tue, 10 Dec 2013 17:15:29 -0800

I will probably reply back to the my question because I just came across
the URL standards and it does seem that I was mis-informed about urls not
being case sensitive.

http://www.w3.org/TR/WD-html40-970708/htmlweb.html

Now considering the fact that they indeed ARE case sensitive, I was
wondering if it would make more sense to clients and developers to always
use lower cases in standards (especially when the browsers themselves
convert everything to lower case). It's my suggestion as a developer who
plans to implement SCIM. It just makes more sense.

On Tue, Dec 10, 2013 at 4:45 PM, Shivang Shah <[email-masked]> wrote:

> I had couple of questions regarding the SCIM api endpoints discussed here
> : http://www.simplecloud.info/specs/draft-scim-api-01.html and I thought
> this might be a good place to start with.
>

---

From: Phil Hunt <[email-masked]>
Date: Tue, 10 Dec 2013 19:07:27 -0800

I am not sure what you have been looking at but most examples I have seen use proper case names for object types in REST. I don't think it is a hard rule-just what I have seen. 

However the spec so far is clear on proper case usage for scim. If your server lowercases things it would cause it to have restore case on out output (eg location). 

For me, I don't see a real reason to change case at this time. 

Phil

> On Dec 10, 2013, at 17:15, Shivang Shah <[email-masked]> wrote:
> 
> I will probably reply back to the my question because I just came across the URL standards and it does seem that I was mis-informed about urls not being case sensitive. 
> 
> Now considering the fact that they indeed ARE case sensitive, I was wondering if it would make more sense to clients and developers to always use lower cases in standards (especially when the browsers themselves convert everything to lower case). It's my suggestion as a developer who plans to implement SCIM. It just makes more sense. 
> 
> 
>> (Apologize if this is double posting ! I posted previously before I was subscribed to the listing!)
>> 
>> I had couple of questions regarding the SCIM api endpoints discussed here : http://www.simplecloud.info/specs/draft-scim-api-01.html and I thought this might be a good place to start with.
>> 
>> "The SCIM protocol specifies well known endpoints and HTTP methods for managing Resources defined in the core schema; i.e., User and Group Resources correspond to /Users and /Groups respectively. Service Providers that support extended Resources SHOULD define Resource endpoints using the established convention; pluralize the Resource name defined in the extended schema by appending an 's'. Given there are cases where Resource pluralization is ambiguous; e.g., a Resource named 'person' is legitimately 'persons' and 'people' Consumers SHOULD discover Resource endpoints via the Schema Sub-Attribute 'endpoint'. "
>> 
>> 1) I have never seen Capitalization of the Resource name before. Is this something new for SCIM? Urls in browsers (urls anywhere for that matter) are by default case insensitive and it doesn't matter if we capitalize it or not. My real question would be is capitalizing the Resource name a part of the spec or just an example?
>> 2) (This might be bit more of a mesh up question between REST spec and SCIM). We have a scenario where a user HAS "favorites". There are 2 ways we can handle this: 
>> 
>> /scim/v1/users/{userId}/favorites (we can call this an extended sub-resource)
>> 
>>  
>> OR
>> 
>> /scim/favorites/users/{userId} (we can all this an extended resource "favorites"). 
>> 
>> From the url perspective both seem to be right but what I don't know is which one is more suitable according to SCIM (and maybe REST? ) specifications. And a follow up question to that might be, do the extended resources have to be capitalized as well?
>> 
>> All help is appreciated! I am new to implementing and understanding SCIM, so please forgive me if I have missed some subtle pointers in the specifications itself!
>> 
> _______________________________________________
> scim mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/scim

---

From: Shivang Shah <[email-masked]>
Date: Tue, 10 Dec 2013 20:09:16 -0800

Phil,

Thanks for the reply back. And I respectfully beg to differ. 2 things:

1) on windows servers urls are case insensitive.
https://www.google.com/#q=windows+server+url+case+sensitive
How do we plan to handle that? Wouldn't it cause issues if someone migrates
from linux to windows servers if proper care is not taken by developers
while implementing their SCIM+REST platform that indeed they will have to
make their urls such that migration won't be a problem while keeping in
mind that they will have to adhere to specifications?

2)  I will quote some examples herewith as to what developers (and probably
SCIM implementers) like me will be expecting if I think of SCIM as REST
based implementation. As of now, all the 3rd party REST apis I have
integrated with, I have always seen them follow all lower cases for their
implementations. Here are some examples:

LINKEDIN:

http://api.linkedin.com/v1/people/~/connections<http://developer.linkedin.com/documents/connections-api#>
http://api.linkedin.com/v1/people/id=12345/connections<http://developer.linkedin.com/documents/connections-api#>

http://api.linkedin.com/v1/people/~/connections:(headline,first-name,last-name)<http://developer.linkedin.com/documents/connections-api#>
http://api.linkedin.com/v1/people/url=http%3A%2F%2Fwww.linkedin.com%2Fin%2Flbeebe/connections<http://developer.linkedin.com/documents/connections-api#>

GOOGLE:

GET https://www.googleapis.com/plus/v1/people/userId

SALESFORCE:

   - For authorization:
   https://login.salesforce.com/services/oauth2/authorize
   - For token requests: https://login.salesforce.com/services/oauth2/token
   - For revoking OAuth tokens:
   https://login.salesforce.com/services/oauth2/revoke

They could have used /OAuth2 or /Token or /People or /Connections, but from
my experience and knowledge, I have always seen them to be lowercase
(twitter as well btw)

And there will probably be some more examples that I can come up with. My
point being (and yes I don't think its set in stone), if something is
accepted widely in developer community, and if it makes their life easier,
it should be taken into consideration.

I will give another example. OAuth2.0 specs do not have any mention (or
alteast i didn't see any in the drafts) as to what authorization endpoints
or token request endpoints should be. But now it's widely accepted among
developers and implementers that /oauth2/authorize OR /oauth2/auth are
considered to be authorization endpoints. Here's an example from salesforce

http://www.salesforce.com/us/developer/docs/api_rest/Content/intro_understanding_oauth_endpoints.htm

But, when URLs are made a part of the specification, it will be set in
stone. Should a thought be given to somehow not force implementers to
follow a very specific set of urls (and url rules there-in) but instead let
the initial implementers decide on that and eventually gain developer
community support? And if we do want to force a very specific set of urls
as a part specifications, then we should get inputs and have discussions
with people out there who are actually going to use and implement these
specifications .. people who will be using scim as means to
provisioning/deprovisioning users in applications such as google,
salesforce (and many others)

Yes, people will follow whats going to be written in the specs. Upper or
Lowercases urls is not an issue once it's in the specs, that's what will be
implemented. But as leads of writing these specifications, thoughts should
be given as to how it will be really put to practice in real world. How
developers like me would be using it. How comfortable they will be
conforming to these specifications. TechGiants like google, linkedin
(probably salesforce?) etc might have all their REST urls lower cased, how
awkward would developers in these companies feel to introduce an
implementation which is different from their whole platform, only because
they are following specifications (and yes, vice versa case is true as well
where they MIGHT have all the urls properly Uppercased for objects, and if
we lowercase urls in scim specs then they will feel awkward. But as you can
see from the examples, the widely accepted norm is lowercasing)

PS: On a side note, I am very new to these kind of discussions and if I
ever step out of line, please do forgive my ignorance :).

On Tue, Dec 10, 2013 at 7:07 PM, Phil Hunt <[email-masked]> wrote:

> I am not sure what you have been looking at but most examples I have seen
> use proper case names for object types in REST. I don't think it is a hard
> rule-just what I have seen.
>
> However the spec so far is clear on proper case usage for scim. If your
> server lowercases things it would cause it to have restore case on out
> output (eg location).
>
> On Tue, Dec 10, 2013 at 4:45 PM, Shivang Shah <[email-masked]>wrote:
>
>> Hi Everyone,
>>

---

From: Phil Hunt <[email-masked]>
Date: Tue, 10 Dec 2013 20:16:49 -0800

I think you miss my point. Case is arbitrary and the precedence was set by scim 1. There is a mandate not to make major breaking changes unless there is a compelling reason. 

Yes, windows servers support case insensitivity urls. But that doesn't mean they can't comply with case sensitive urls. 

Phil

> On Dec 10, 2013, at 20:09, Shivang Shah <[email-masked]> wrote:
> 
> Phil, 
> 
> 1) on windows servers urls are case insensitive. https://www.google.com/#q=windows+server+url+case+sensitive
> How do we plan to handle that? Wouldn't it cause issues if someone migrates from linux to windows servers if proper care is not taken by developers while implementing their SCIM+REST platform that indeed they will have to make their urls such that migration won't be a problem while keeping in mind that they will have to adhere to specifications?
> 
> 2)  I will quote some examples herewith as to what developers (and probably SCIM implementers) like me will be expecting if I think of SCIM as REST based implementation. As of now, all the 3rd party REST apis I have integrated with, I have always seen them follow all lower cases for their implementations. Here are some examples:
> 
> LINKEDIN:
> http://api.linkedin.com/v1/people/~/connections
> http://api.linkedin.com/v1/people/id=12345/connections
> 
> http://api.linkedin.com/v1/people/~/connections:(headline,first-name,last-name)
> http://api.linkedin.com/v1/people/url=http%3A%2F%2Fwww.linkedin.com%2Fin%2Flbeebe/connections
> 
> GOOGLE:
> 
> For authorization: https://login.salesforce.com/services/oauth2/authorize
> For token requests: https://login.salesforce.com/services/oauth2/token
> For revoking OAuth tokens: https://login.salesforce.com/services/oauth2/revoke
> 
> They could have used /OAuth2 or /Token or /People or /Connections, but from my experience and knowledge, I have always seen them to be lowercase (twitter as well btw)
> 
> And there will probably be some more examples that I can come up with. My point being (and yes I don't think its set in stone), if something is accepted widely in developer community, and if it makes their life easier, it should be taken into consideration. 
> 
> I will give another example. OAuth2.0 specs do not have any mention (or alteast i didn't see any in the drafts) as to what authorization endpoints or token request endpoints should be. But now it's widely accepted among developers and implementers that /oauth2/authorize OR /oauth2/auth are considered to be authorization endpoints. Here's an  example from salesforce
> 
> But, when URLs are made a part of the specification, it will be set in stone. Should a thought be given to somehow not force implementers to follow a very specific set of urls (and url rules there-in) but instead let the initial implementers decide on that and eventually gain developer community support? And if we do  want to force a very specific set of urls as a part specifications, then we should get inputs and have discussions with people out there who are actually going to use and implement these specifications .. people who will be using scim as means to provisioning/deprovisioning users in applications such as google, salesforce (and many others)
> 
> Yes, people will follow whats going to be written in the specs. Upper or Lowercases urls is not an issue once it's in the specs, that's what will be implemented. But as leads of writing these specifications, thoughts should be given as to how it will be really put to practice in real world. How developers like me would be using it. How comfortable they will be conforming to these specifications. TechGiants like google, linkedin (probably salesforce?) etc might have all their REST urls lower cased, how awkward would developers in these companies feel to introduce an implementation which is different from their whole platform, only because they are following specifications (and yes, vice versa case is true as well where they MIGHT have all the urls properly Uppercased for objects, and if we lowercase urls in scim specs then they will feel awkward. But as you can see from the examples, the widely accepted norm is lowercasing)
> 
> PS: On a side note, I am very new to these kind of discussions and if I ever step out of line, please do forgive my ignorance :).
> 
>

---

From: Shivang Shah <[email-masked]>
Date: Tue, 10 Dec 2013 20:35:56 -0800

oh I see .. I am sorry I was not aware of the mandate to not make major
breaking changes. But one could argue the same way that instead of making
implementers comply with case sensitive urls (which might be awkward for
them), it'd be probably ok to make a change in the spec, especially when
(and please do correct me if I am wrong here) the spec is moving one major
version up from 1.1 to 2.0 ? Urls do change when the API versions change,
especially when there are major version changes. I think I am failing to
understand as to how big of an impact would this change in the spec be?

Developers and Implementers comfort with the specifications should be (and
again, this is just my personal view, till the time we make this an open
discussion on forums to see what other developers think) a good enough
compelling reason to change the spec with a major version change. That
would be my 2 cents.

On Tue, Dec 10, 2013 at 8:16 PM, Phil Hunt <[email-masked]> wrote:

> I think you miss my point. Case is arbitrary and the precedence was set by
> scim 1. There is a mandate not to make major breaking changes unless there
> is a compelling reason.
>
> Yes, windows servers support case insensitivity urls. But that doesn't
> mean they can't comply with case sensitive urls.
>
> Phil
>
> How do we plan to handle that? Wouldn't it cause issues if someone
> migrates from linux to windows servers if proper care is not taken by
> developers while implementing their SCIM+REST platform that indeed they
> will have to make their urls such that migration won't be a problem while
> keeping in mind that they will have to adhere to specifications?
>
> 2)  I will quote some examples herewith as to what developers (and
> probably SCIM implementers) like me will be expecting if I think of SCIM as
> REST based implementation. As of now, all the 3rd party REST apis I have
>    - For token requests:
>    https://login.salesforce.com/services/oauth2/token
> They could have used /OAuth2 or /Token or /People or /Connections, but
> from my experience and knowledge, I have always seen them to be lowercase
> (twitter as well btw)
>
>>> I had couple of questions regarding the SCIM api endpoints discussed
>>> here : http://www.simplecloud.info/specs/draft-scim-api-01.html and I
>>> thought this might be a good place to start with.
>>>
>>> All help is appreciated! I am new to implementing and understanding
>>> SCIM, so please forgive me if I have missed some subtle pointers in the
>>> specifications itself!
>>>

---

From: Shivang Shah <[email-masked]>
Date: Wed, 11 Dec 2013 08:47:03 -0800

All,

I had another follow up question to this thread. As per the spec here:

The SCIM protocol specifies well known endpoints and HTTP methods for
   managing Resources defined in the core schema; i.e., User and Group
   Resources correspond to /Users and /Groups respectively.  Service
   Providers that support extended Resources SHOULD define Resource
   endpoints using the established convention; pluralize the Resource
   name defined in the extended schema by appending an 's'.  Given there
   are cases where Resource pluralization is ambiguous; e.g., a Resource
   named 'person' is legitimately 'persons' and 'people' Consumers
   SHOULD discover Resource endpoints via the Resource Type attribute
   'endpoint'.

I see that there is not much information on the extended subresources of
the already defined well known endpoints. Here's an example.

Suppose an application has a User who HAS assigned Projects which inturn
HAS assigned Tasks per project. In this case, the REST urls would look
something like:

scim/v1/Users/{userId}/Projects/{projectId}/tasks.

My question is: does this still comply SCIM specs? Or resource handling
like these should be on a separate REST platform because it doesn't have
anything to do directly with Identity Management (although one might argue
that these could be entitlements assigned to the User)

Another question here would be, if I am someone trying to write a generic
SCIM-REST client based off of the specs, how would I take into
consideration and handle the above resources because from what it seems,
each scim service provider could have their own Object that a User gets in
their application (or gets assigned to), for eg: Projects in the above
case.

I guess it's more of a design question as to where a service provider
should draw the line and encapsulate their apis as SCIM apis or dedicated
REST apis.

Anyone has any suggestions for me? We have started implementing scim on our
platform and we would like to comply as much as we can with the specs.

On Tue, Dec 10, 2013 at 8:35 PM, Shivang Shah <[email-masked]> wrote:

>> I think you miss my point. Case is arbitrary and the precedence was set
>> by scim 1. There is a mandate not to make major breaking changes unless
>> there is a compelling reason.
>>
>>> I am not sure what you have been looking at but most examples I have
>>> seen use proper case names for object types in REST. I don't think it is a
>>> hard rule-just what I have seen.
>>>
>>>> 1) I have never seen Capitalization of the Resource name before. Is
>>>> this something new for SCIM? Urls in browsers (urls anywhere for that
>>>> matter) are by default case insensitive and it doesn't matter if we
>>>> capitalize it or not. My real question would be is capitalizing the
>>>> Resource name a part of the spec or just an example?