Note that there are some explanatory texts on larger screens.

plurals
  1. PO
    primarykey
    data
    text
    <p>URLs have always been case sensitive. HOST names, however, are not.</p> <p><code>http://example.com/User?id=JohnDoe</code> and <code>http://ExAmPlE.cOM/User?id=JohnDoe</code> should resolve to the same resource, even though the URLs are not identical. But the URL is case sensitive.</p> <p>Since the spec is specifying <code>Users</code> rather than <code>users</code>, the casing is significant.</p> <p>It's significant because the spec says so. Also, if nothing else, others who read the spec will be using <code>Users</code> vs <code>users</code>.</p> <p>Regarding REST, these URLs wouldn't matter, since REST doesn't care about URLs.</p> <p>But this is not REST. This is an HTTP based specification. It has nothing to do with REST.</p> <p>Addenda:</p> <p>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.</p> <p>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.</p> <p>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.</p> <p>This spec has little of that.</p> <p>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.</p> <p>Consider the PATCH section where they talk about deleting a User from a group. They have:</p> <pre><code> "display": "Babs Jensen", "value": "2819c223-7f76-453a-919d-413861904646" "operation": "delete" </code></pre> <p>What is <code>value</code>? Looks like some kind of "user id". Yet, the URL should be the User ID. Whether it's <a href="http://example.com/Users/1234" rel="nofollow">http://example.com/Users/1234</a> or <a href="http://example.com/shippingdepartment/v1/Users/1234" rel="nofollow">http://example.com/shippingdepartment/v1/Users/1234</a> or <a href="http://example.com/beta/notforpublication/Users/1234" rel="nofollow">http://example.com/beta/notforpublication/Users/1234</a>. THAT's a unique identifier. What does simply <code>1234</code> tell you? Not enough.</p> <p>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. </p> <p>What happens when you want to GET: <a href="http://www.example.com/Users/1234" rel="nofollow">http://www.example.com/Users/1234</a> and they changed over to /v2? In REST on HTTP, the server can respond with a <code>301 Moved Permanently</code> with a Location: <a href="http://www.beta.example.com/v2/users/4567/core" rel="nofollow">http://www.beta.example.com/v2/users/4567/core</a>. 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?</p> <p>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.</p> <p>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.</p> <p>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.</p>
    singulars
    1. This table or related slice is empty.
    plurals
    1. This table or related slice is empty.
    1. This table or related slice is empty.
    1. This table or related slice is empty.
    1. VO
      singulars
      1. This table or related slice is empty.
    2. VO
      singulars
      1. This table or related slice is empty.
 

Querying!

 
Guidance

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload