I work for a large company which has several non-RESTful APIs. I am tasked with building a web application to interact with these APIs. Each API handles and provides very different business processes and data.

I'd like to build RESTful (a) interface(s) fronting the APIs so as to make them reusable by other future web applications. Then, I'd like JavaScript to interact with the RESTful interface(s).

Should I build one RESTful API (one subdomain) for my entire company


and make it front the very different business processes and data? Or, should I build multiple APIs (multiple subdomains)?

  • There is an important related question on SO that discusses API versioning that puts this question into context: stackoverflow.com/a/398564/396747
    – Gary
    Commented Jul 25, 2012 at 10:27

3 Answers 3


The key question here is whether your company is liable to sell/divest any of its divisions or products?

If the answer is yes then you probably want to have a url per brand or per product. If your company is a "single product" company then a single URL is the way to go.

  • Good point. This is all internal, so luckily there are no liability concerns. Commented Jul 24, 2012 at 1:50

REST is not the URI

The most common implementation of REST consists of the combination of URIs, HATEOAS and HTTP verbs. Therefore I would suggest that focusing on creating a URI structure is a little premature.

Fundamentally, you should design your API so that it is discoverable by a client that understands the content of the payload. For example, ensuring that your payload contains links with rels and microformats means that your clients become less reliant on the URIs and more reliant on what is contained in the payload to drive them.

In this way, you can direct your clients to the most appropriate version of their APIs through links with semantics that they have been programmed to understand, usually through appropriate use of HTTP status codes.

For a general purpose, lightweight, payload format consider Hypertext Application Language (HAL).

And what about my question?

That said, multiple sub-domains with JavaScript leads to cross domain issues which (although mitigated using the document.domain approach) lead to client complexity. From that standpoint alone, you should consider a single starting point and build out from there.


I would probably run with a single URL fronting the web services for matter of simplicity on some levels. With modern proxies and load balancing tricks a single URL will not tie your hands insofar as infrastructure options go.

The most crucial piece of your URL strategy is missing -- version your API. That is the one thing that will get you into trouble insofar as your URLs are concerned. Everything else is fixable with a new endpoint.

Implementation-wise, you are most likely going to want to go for individual endpoints rather than something monolithic -- you will thank yourself in the long term. It will let you get out of the door quicker in almost all cases to boot.

  • Thank you for your feedback. Might this look like using multiple endpoints reverse-proxied or virtually mounted under one domain? Example: api.company.com/api1/resource, api.company.com/api2/resource; api1 and api2 are different endpoints possibly hosted on different machines and different vhosts. Commented Jul 24, 2012 at 0:53
  • 1
    Use data content for versioning - then you use the same URL but the contents are routed according to the version number you embed in each request. This allows you to upgrade 'silently' without changing every client's bookmarks. eg. mcavage.github.com/node-restify/#Routing
    – gbjbaanb
    Commented Jul 24, 2012 at 9:21
  • -1 for putting the version on the API. This is poor RESTful practice.
    – Gary
    Commented Jul 24, 2012 at 9:28
  • I'd actually rather break URLs for breaking changes between versions -- forces a client to actively upgrade, not just repoint automagically. Commented Jul 24, 2012 at 12:13
  • @WyattBarnett Why make work for the client? Think of them like browsers and use a format that allows them to adapt. You can support your old API by means of the Accept header (e.g. "Accept: application/barnett.apiv1+json) and then have more modern clients offer alternatives (e.g. "Accept: application/barnett.apiv1+json;q=0.8;application/barnett.apiv2+json;q=0.9"). Your server then knows how to represent the resources for that client. See stackoverflow.com/a/398564/396747
    – Gary
    Commented Jul 25, 2012 at 10:26

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.