Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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
share|improve this question
    
There is an important related question on SO that discusses API versioning that puts this question into context: stackoverflow.com/a/398564/396747 –  Gary Rowe Jul 25 '12 at 10:27

3 Answers 3

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.

share|improve this answer

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.

share|improve this answer
    
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. –  Chad Johnson Jul 24 '12 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 Jul 24 '12 at 9:21
    
-1 for putting the version on the API. This is poor RESTful practice. –  Gary Rowe Jul 24 '12 at 9:28
    
I'd actually rather break URLs for breaking changes between versions -- forces a client to actively upgrade, not just repoint automagically. –  Wyatt Barnett Jul 24 '12 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 Rowe Jul 25 '12 at 10:26

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.

share|improve this answer
    
Good point. This is all internal, so luckily there are no liability concerns. –  Chad Johnson Jul 24 '12 at 1:50

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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