Search code examples
resthttpdesign-patternsrestful-url

How to design RESTful API URI when you can't have user ID on the URI

Make-up scenario:

Let's say I am building a RESTful Web API backend for managing the payment plans for members:

  • It's for members so you would have to register with us. Each member would have a member ID internally.
  • There are various payment plans: 0% interest for 6 months, 0% interest for 12 months, etc. Each payment plan would have an ID internally.
  • The relationship between member and payment plan is many-to-many.
  • Each member also would have 1 active plan at a time. You can change it, but there is only 1 active plan allowed for a member.

Now if I want to design an API endpoint to return the information about the member active payment plan, I would normally do something like:

/members/{member-id}/plans/active

I understand that it might be a bad idea to put state on the URI (I had a separate question for that matter), but please bear with me.

Now here is the tricky part: the company's policy states that I can't have the member ID in the URI. They will have some kind of tokens in HTTP header, which is required in order to access the RESTful API endpoints, that contains the member ID.

My API application, which is ASP.NET Core Web API by the way, has no problem creating a filter to parse that token and transform it into member ID, in the code. It's just that my API URIs can't have the member ID anymore.

How would you design the URI in this case?

Without the member ID on the URI, mine would look like

/plans/active

And the data now would be all driven/filtered by that member ID, securely inside the API backend. Is this normal?

Solution

  • the data now would be all driven/filtered by that member ID, securely inside the API backend. Is this normal?

    It sounds to me as though things are going sideways; as though people don't understand REST, or that people don't understand that what they are trying to achieve isn't a good fit for REST.

    In order to obtain a uniform interface, multiple architectural constraints are needed to guide the behavior of components. REST is defined by four interface constraints: identification of resources.... -- Fielding, 2000

    REST uses a resource identifier to identify the particular resource involved in an interaction between components. REST connectors provide a generic interface for accessing and manipulating the value set of a resource, regardless of how the membership function is defined or the type of software that is handling the request. The naming authority that assigned the resource identifier, making it possible to reference the resource, is responsible for maintaining the semantic validity of the mapping over time (i.e., ensuring that the membership function does not change). -- Fielding, 2000

    The web works on the shared understanding that uniform resource identifiers identify resources. The URI is the key of the key/value store. When you start moving identifying information into other parts of the request, then you are opting out of the "uniform interface" that is shared by everyone else. This puts interop at risk.

    On the other hand, much of the web also assumes that identifiers are published, and there isn't in general a lot of discipline to restrict the copying of them. So you certainly don't want secrets and/or sensitive information included.

    The answer in REST is to use another layer of indirection. The rule is that we should be using a URI, and each identifier should map to one resource. But there's no rule that says that the spelling of the URI must match the semantics of the resource.

    In other words: URL shorteners work!

    GET /99bfb1e3-89a4-4a44-a6d7-0e70c209f447 HTTP/1.1

    As far as REST is concerned, that's a perfectly valid request, with an entirely satisfactory identifier. As long as your server understands how to find the secrets using that key, then that's fine.

    Of course, you could add semantic information to the URI that isn't sensitive, to help the humans orient to the context

    GET /members/99bfb1e3-89a4-4a44-a6d7-0e70c209f447/plans/active HTTP/1.1
GET /members/plans/active/99bfb1e3-89a4-4a44-a6d7-0e70c209f447 HTTP/1.1
GET /members/plans/active?99bfb1e3-89a4-4a44-a6d7-0e70c209f447 HTTP/1.1

    These are all also fine (again, assuming that you can use the information provided to discover the sensitive information you need to produce/modify the corresponding resource).

    On the other hand, if your organization's concerns are related to leaking the identifier itself... then somebody with seniority should really be challenging the assumption that REST/HTTP is the right answer to the problem.

    As your deviate further from the "standard" for HTTP messages, you increase the risk that some general purpose component isn't going to understand what is going on, and if that results in significant loss of property, your lawyers aren't going to be happy.