25

Let's say I have a company that ranks the cutest cats on the internet.

I offer a resource at /cats/ which provides users with the latest, cutest adorable cats.

Users can either get just the top 3 cats if they haven't paid at all or registered. The top 10 cats if they paid 337 dollars and are logged in, and the top 100 cats if they paid 1337 dollars and are logged in. I have a 'user identifier' when making the request.

In short, consumers of /cats/ get a different number of cats based on their 'user ranking'. I do have a user identifier on the consuming end, but I have no explicit representation of the user level on the consuming end. I'd like to inform users they can upgrade their subscription when making the request. That is, I need to distinguish between 3 cats since I only offer 3 cats and 3 cats because that's what the user level allowed.

What is the best practice for distinguishing limiting the resource because the consumer does not have sufficient priviledges and limiting it because that's what the consumer has?

How does the client know if they can upgrade their ranking? That is, they only got a limited resource because they don't have permissions. What is the best practice here?

Note, this is a gross simplification of the actual case. Also, just to clarify - reading is appreciated.

Update:

Here are options we've considered:

  • Storing the user permissions objects once on the client, querying for it only when account login or upgrade is performed.
  • Passing null values in JSON indicating it exists, but an actual nothing was transfered. So 10 cats for a user with 3 cats could be ["Garfield","Sylvester","Puss in Boots",null*7]
  • Passing a resource permission pair {cats:["Whiskers","Fluffy","Socks"],authCount:3}

I'd like to do this right the first time to deliver the cutest cats in the best way possible and we'd and we'd like

Community
  • 1
Benjamin Gruenbaum
  • 5,157
  • 4
  • 24
  • 34

2 Answers2

19

I'd say it depends on your audience.

No-dev

If your audience is not a developer's one, I'd go with the following way:

Let's say you return JSON for the sake of the example.

GET /cats HTTP/1.1

{
    "cats": [
        "Can I haz cheeseburger",
        "If it fits, I sits",
        "It's caturday!"
    ],
    "permissions": {
        "level": "free",
        "information": "You have access to 3 cats. Upgrade to ... to get 10 cats!"
    }
}

Or something similar.

It is informative for the user to know what the status of his account is, and it allows you to put whatever information you want, such as a marketing message. The most important point of this way is to give some easy visibility to your users of their current account.

Dev

However, if your audience is purely developers, then I'd say: go with the full HTTP compliant way. To store the metadata, you use HTTP headers.

Here is an example:

GET /cats HTTP/1.1

X-Account: anonymous
X-Account-Possible-Upgrades: 2
X-Account-Limit: 3

Then, provide a clear documentation of what these headers mean. Most developers will go straight for the documentation when they'll see these custom headers, especially if they're seeing a limit. You can go even further and show the link in the headers. Or you can show a link to the pricing page.

X-Account-Doc: http://your/doc

But then again, many developers don't know how HTTP works.

So it's your call

One is more correct, the other is more accessible.

Misc

Some other miscellaneous stuff related to your question:

Community
  • 1
Florian Margaine
  • 6,791
  • 3
  • 33
  • 46
  • 1
    Yeah, this makes absolute sense, though as a side note I find some of the auth(ent/orize) information going in the HTTP headers is an appropriate approach as it is effectively metadata. – Jimmy Hoffa Jul 08 '13 at 15:31
  • @JimmyHoffa It is indeed metadata, and my first thought was to use the HTTP headers. However, in this case, HTTP headers don't offer enough visibility for the customer, and granularity needed for marketing messages. (Edited the answer to add this detail.) – Florian Margaine Jul 08 '13 at 15:32
  • @JimmyHoffa how? An 402 won't do in this case. What do you suggest? – Benjamin Gruenbaum Jul 08 '13 at 15:47
  • @BenjaminGruenbaum I didn't say response codes, I said headers; you can add all the custom headers you want for metadata, it would be wise to have all responses from a restful api just have the users role in the header as a `UserRole = level1` or whatever you wish to call it just to ensure consumers are always aware how to present any data they receive, and it's consistent across all responses where the data models coming back will be different from one request to another, consumers can always check their role the same way. – Jimmy Hoffa Jul 08 '13 at 15:54
  • @JimmyHoffa you're welcome to post an answer with a suggested scheme and why you think it's the best practice :) – Benjamin Gruenbaum Jul 08 '13 at 15:56
  • @BenjaminGruenbaum nah, Florian's answer is correct, you should accept it. My suggestion's just a sidenote. – Jimmy Hoffa Jul 08 '13 at 15:58
  • 1
    @BenjaminGruenbaum I've completely rewritten the answer. – Florian Margaine Jul 08 '13 at 17:57
  • @JimmyHoffa I think you will like the new answer :) – Florian Margaine Jul 08 '13 at 18:06
  • I don't think that HTTP response headers make it here, those are not request limits or similar. – hakre Jul 08 '13 at 18:09
  • @JimmyHoffa Just bear in mind that custom headers are not guaranteed to make it across proxies or through firewall software... – Marjan Venema Jul 08 '13 at 20:18
  • @MarjanVenema that's actually a great point I didn't even consider, some networks do clean that stuff out, but then that kinda falls under the same guise as remembering some people run their browsers without javascript, that doesn't mean you shouldn't write javascript run websites, it just means some people are using a version of the web that harkens them back to the mid 90's when most pages hardly worked. – Jimmy Hoffa Jul 08 '13 at 20:52
  • @JimmyHoffa: yup, then again, for some people it is not a choice but a consequence of their employers getting a false sense of security (or pat on the back from their lawyers) out of plugging every hole they can think of regardless of what it does to their employee's productivity. I have had the misfortune of being employed by such a misinformed ill-advised business and very glad I left. – Marjan Venema Jul 08 '13 at 21:17
  • Since the caller is expecting top cats, returning permission is undesirable. I would rather make a separate call to know for user permissions. This way I can reuse user permissions in various places. – kumards Nov 07 '16 at 14:35
4

How does the client know if they can upgrade their ranking?

That depends on the client. Normally you can put such information in form of a hyptertext message (aka HTML) into the response body of the REST method. However that only makes sense if the REST API is used with a HTML client.

Similar for XML and JSON.

Edit: You might confuse using an API (expand this acronym) with the marketing of your account-types / user-plans. I would not mix this, as it always gets fishy (business decisions might requires faster changes than the changes in the software to communicate different responses due to these changes are able to get on the platter in time).

Instead tell your users through a different channel, e.g. with the newsletter what their benefits are.

This works particularly well when the person signing up to the service isn't the one who is programming against the API. For example:

George (who is a proudly gay guy at the age of 36 loving kittens) buys access to cute-cats-4-me.com and tells his 16 year old spouse (who is well with scripting computer systems incl. linux) to create a digital signage application displaying nice little cutie kitties on the wall in the apartment.

So the guy who is having fun programming this actually is not that much the most straight-forward addressee of the information.

Alternatively in response to login and a user-info method, provide all the gory details.

But when a user requests cats programmatically, she should be already aware why she only gets three cats back or more. But you don't solve this communication problem with code.

Otherwise, allow them to query more and then give back a failure notice if their rights are not sufficient. But again, that's not a user-friendly software.

hakre
  • 1,165
  • 12
  • 17
  • 1
    @Racheet: Do you have a problem when the girls have the money in the house and tell the boys what to do? – hakre Jul 08 '13 at 18:08
  • 2
    I have a problem with an example which asserts that girls need boyfriends to do their programming for them. – Racheet Jul 09 '13 at 09:02