CODEWITHSUNDEEP
apirestauthenticationauthorization
alecswan
alecswan

Reputation: 3680

How RESTful is using subdomains as resource identifiers?

We have a single-page app (AngularJs) which interacts with the backend using REST API. The app allows each user to see information about the company the user works at, but not any other company's data. Our current REST API looks like this:

domain.com/companies/123
domain.com/companies/123/employees
domain.com/employees/987

NOTE: All ids are GUIDs, hence the last end-point doesn't have company id, just the employee id.

We recently started working on enforcing the requirement of each user having access to information related exclusively the company where the user works. This means that on the backend we need to track who the logged in user is (which is simple auth problem) as well as determining the company whose information is being accessed. The latter is not easy to determine from our REST API calls, because some of them do not include company id, such as the last one shown above.

We decided that instead of tracking company ID in the UI and sending it with each request, we would put it in the subdomain. So, assuming that ACME company has id=123 our API would change as follows:

acme.domain.com
acme.domain.com/employees
acme.domain.com/employees/987

This makes identifying the company very easy on the backend and requires minor changes to REST calls from our single-page app. However, my concern is that it breaks the RESTfulness of our API. This may also introduce some CORS problems, but I don't have a use case for it now.

I would like to hear your thoughts on this and how you dealt with this problem in the past.

Thanks!

Upvotes: 3

Views: 2137

Answers (2)

Javier Ramirez
Javier Ramirez

Reputation: 4032

There is nothing "unrestful" in using subdomains. URIs in REST are opaque, meaning that you don't really care about what the URI is, but only about the fact that every single resource in the system can be identified and referenced independently.

Also, in a RESTful application, you never compose URLs manually, but you traverse the hypermedia links you find at the API endpoint and in all the returned responses. Since you don't need to manually compose URIs, from the REST point of view it's indifferent how they look. Having a URI such as //domain.com/ABGHTYT12345H would be as RESTful as //domain.com/companies/acme/employees/123 or //domain.com/acme/employees/smith-charles or //acme.domain.com/employees/123

All of those are equally RESTful.

But... I like to think of usable APIs, and when it comes to usability having readable meaningful URLs is a must for me. Also following conventions is a good idea. In your particular case, there is nothing unrestful with the route, but it is unusual to find that kind of behaviour in an API, so it might not be the best practice. Also, as someone pointed out, it might complicate your development (Not specifically on the CORS part though, that one is easily solved by sending a few HTTP headers)

So, even if I can't see anything non REST on your proposal, the conventions elsewhere would be against subdomains on an API.

Upvotes: 1

Will Dean
Will Dean

Reputation: 39520

In a similar application, we did put the 'company id' into the path (every company-specific path), not as a subdomain.

I wouldn't care a jot about whether some terminology enthusiast thought my design was "RESTful " or not, but I can see several disadvantages to using domains, mostly stemming from the fact that the world tends to assume that the domain identifies "the server", and the path is how you find an item on that server. There will be a certain amount of extra stuff you'll have to deal with with multiple domains which you wouldn't with paths:

  • HTTPS - you'd need a wildcard certificate instead of a simple one
  • DNS - you're either going to have wildcard DNS entries, or your application management is now going to involve DNS management
  • All the CORS stuff which you mention - may or may not be a headache in your specific application - anything which is making 'same domain' assumptions about security policy is going to be affected.

Of course, if you want lots of isolation between companies, and effectively you would be as happy running a separate server for each company, then it's not a bad design. I can't see it's more or less RESTful, as that's just a matter of viewpoint.

Upvotes: 3

Related Questions