SCIM endpoints and other extended Resources in SCIM

Question

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!

Answer 1

URLs have always been case sensitive. HOST names, however, are not.

http://example.com/User?id=JohnDoe and http://ExAmPlE.cOM/User?id=JohnDoe should resolve to the same resource, even though the URLs are not identical. But the URL is case sensitive.

Since the spec is specifying Users rather than users, the casing is significant.

It's significant because the spec says so. Also, if nothing else, others who read the spec will be using Users vs users.

Regarding REST, these URLs wouldn't matter, since REST doesn't care about URLs.

But this is not REST. This is an HTTP based specification. It has nothing to do with REST.

Addenda:

They can call it a REST API all they like, it doesn't make it so. They also call it a "REST protocol", which makes no sense since REST is an architecture. HTTP is a protocol. You can build a REST architected application on top of HTTP, but you don't have to. REST is unrelated to HTTP.

REST doesn't care about URLs for the same reason you don't. A key tenet in REST is HATEOAS, which is essentially identifying links within the resources and following them. Do you know what the "checkout" link is for Amazon? No? Yet you still manage to shop there? That's possible because you follow the "checkout" link, not because you know what the URL is.

A properly designed client in a REST architecture simply follows the URLs given to it within the payloads. The URLs are opaque to it. The client need only be told of an entry point (the home page if you will) of the service, and it can navigate from there on its own via well know link identifiers (rels) that it finds in the payloads.

This spec has little of that.

Consider in the spec how they say that versioning is OPTIONAL. So, that means a URL can be /v1/Users or just /Users. Which URL do you code in your client? How do you know what version someone is running? What if the service you're using was not versioned before and becomes versioned? All of your URLs break. If you want to make a protocol joyous to implement in the wild, add OPTIONAL elements to fundamentals like how to access it.

Consider the PATCH section where they talk about deleting a User from a group. They have:

  "display": "Babs Jensen",
  "value": "2819c223-7f76-453a-919d-413861904646"
  "operation": "delete"

What is value? Looks like some kind of "user id". Yet, the URL should be the User ID. Whether it's http://example.com/Users/1234 or http://example.com/shippingdepartment/v1/Users/1234 or http://example.com/beta/notforpublication/Users/1234. THAT's a unique identifier. What does simply 1234 tell you? Not enough.

With HATEOAS, your client doesn't have to "know" how to "build" these URLs, and get it wrong. The server tells the client what those are.

What happens when you want to GET: http://www.example.com/Users/1234 and they changed over to /v2? In REST on HTTP, the server can respond with a 301 Moved Permanently with a Location: http://www.beta.example.com/v2/users/4567/core. The server just told your client that this resource has moved. Not just the "ID" (1234 to 4567), but the path (/Users/1234 to /v2/users/4567/core), and even the HOST (www.example.come to www.beta.example.com). How would your client even know how to build the new URL?

So, 1234 isn't enough. An opaque URL is much more robust. Just like you don't care what the value of a pointer is in programming, you only care about what it's pointing too, and why pointer math leads to more trouble.

And if they used the URL in these Groups, then you could have cross domain User Groups! What a novel idea. You could have v1 and v2 users in the same group. All sorts of things.

As for #2, sub resources and what not, that's a matter of taste -- your taste, as you can see, from high level REST perspective, clients don't care what you do.