One or many RESTful APIs for large company?

Question

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

http://api.mycompany.com
    /business_process_1/resource/
    /business_process_2/resource
    /business_process_3/resource

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

http://business-process-1.mycompany.com
http://business-process-2.mycompany.com
http://business-process-3.mycompany.com

Answer 1

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.

Answer 2

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.

Answer 3

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.