Merging API and web app?

[Jack Repenning]

We have an existing web application. We're adding an API, that provides largely the same capabilities but programmatically. We're using the same implementation technology (Ruby on Rails). A question comes up: should we merge the two into a single host/URL?

https://app.ourcompany.com/somepage.html
https://app.ourcompany.com/someresource/id

There seem to be more potential trade-offs here than I can quite keep track of:

Since it's the same functionality, there's lots of opportunity for sharing: database, models, object caches, authentication, sessions, yadda yadda yadda. But some things have no need of sharing, or might even conflict with it: special developer token access, mixed-model authentication, etc.

"Really simple" implementation (all on one box) is just asking for trouble; "darn simple" implementation (app.ourcompany.com and api.ourcompany.com) seems better adaptable to the vagaries of internet traffic; "realistic" implementation, with load balancers and pools of servers and such is probably cheaper (less hardware) if there's only one hostname / pool of resources.

What if we want to rehost the API at a service like Apigee (I know you guys are listening ;-)? Does entangling the API URL with the app URL complicate that?

Jack Repenning

And the next thing you know, you're sucking down Darjeeling with Marie Antoinette and her little sister!

[Arlo Belshee]

You can get a lot of the sharing you mention without necessarily being on the same URL.

Database: can be on a remote machine anyway, so you could share this pretty easily.

Models and caches: at high levels of scale you probably want each host to have its own cache anyway. So the only thing to share is the code. Not really that much cost to lose the sharing at low usage levels.

Identity and sessions: this you do want to share. You'll need to find a solution. But single-sign-on is a solved problem. Auth, as you point out, will be different for the two endpoints, but identity should probably share.

So I wouldn't worry too much about the downsides of splitting the URLs.

Arlo

[Jack Repenning]

On Apr 17, 2012, at 5:58 PM, Arlo Belshee wrote:

> You can get a lot of the sharing you mention without necessarily being on the same URL.

The argument specifically being made in favor of consolidation is code-sharing and deployment-machinery-sharing, more than runtime data sharing of various sorts: a single check out, yields one copy of a given model source code file, a single copy of the unit tests that protect api-developers from mistakes by app-developers and vice versa, and a single "deploy me please" button.

Jack Repenning

[Peter Williams]

On Tue, Apr 17, 2012 at 7:17 PM, Jack Repenning
<repenni...@gmail.com> wrote:
>
> The argument specifically being made in favor of consolidation is
> code-sharing and deployment-machinery-sharing, more than runtime
> data sharing of various sorts: a single check out, yields one copy of a
> given model source code file, a single copy of the unit tests that
> protect api-developers from mistakes by app-developers and vice
> versa, and a single "deploy me please" button.

Most of the systems i have been involved with have used the same code
base to implement both the api and html pages. This does provide
immense benefits, as you mentioned above, when it is feasible (and it
almost always is). In my experience there is a huge upside, and no
significant downside, to implementing both the api and html pages in a
single code base.

(Most of the time i even use the same uris for both the html and api
resources. The content negotiation support in RoR makes doing so quite
easy. OTOH, if you want them to have separate uris the rails router is
easily capable enough to allow it without requiring any duplication of
code.)

The deployment question is less clear cut. I alway use a single
deployment for both html pages and the api, but i can imagine some
scenarios where it might be advantageous to segregate the different
work loads. Practically speaking, though, the additional operational
complexity of having separate deployments for html pages and the api
would rarely be worth it. I'd suggest a single deployment doing both.
You can always split the deployments later if there is ever data
suggesting that it would be beneficial.

Peter
barelyenough.org

[Arlo Belshee]

It's also pretty darned easy to deploy the same code to two different places, so sharing code between two endpoints isn't a challenge.

After all, I assume you're already doing this - you have local dev build, a staging or test environment, and the liver server, right? It's pretty simple to add a couple new servers to the deploy script.

I wouldn't use a cost reason to justify either approach. Both are low cost and allow sharing (especially of static resources such as source).

So make the choice based on the value axis. Which would your customers (end users, programmers of client apps, etc) prefer? They don't care about your costs at all, so what would they like and why?

Arlo

[mca]

Like Peter Williams, my work almost always uses the same
component-level (business layer) code no matter the connector-level
employed (html client, desktop client, mobile, api, etc.).

along w/ saving some repetitive tasks, using the same component layer
for all interfaces makes it much more likely that the various
client-facing implementations exhibit the same business rules.

the exact details of the public identifiers (URIs) for resources are
left to the various front-facing connectors; as long as they are
consistent within the connector-space, that's fine. that said, i
usually try to follow a human-friendly convention of exposing the
mobile interface using m.{primary-domain}.com and the api interface
at api.{primary-domain}.com.

mca
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me

[Jeff Schmidt]

You can get a lot sharing, code consolidation etc. if your application
uses your own APIs.  Does your app need to pull and display the user's
profile? Call your API and render as appropriate.  The API
implementation deals with interacting with backend systems (other APIs
maybe), perform caching, and your application can use the data just as
easily as any other API client/tenant. Whether your application
invokes the API from the server-side or client-side to get what it
needs, depends on your situation.

Your application can authenticate with a higher level of privileges,
and the APIs may provide additional information, or additional APIs
may become available. I don't see why an external API cannot also be
an internal API.  For functionality that is unique to your
application, perhaps some of that can be satisfied by those additional
APIs, while other stuff has no API bearing and is simply application
code.  This way you get to eat your own dog food and get a better
feeling for using your offered APIs. :)

In another thread there was a discussion about supporting multi-
tenancy, whether that be via some kind of tenantId parameter, or using
a unique hostname. Much like your question of app.x.com and api.x.com,
unique host names lend themselves better to infrastructure
customization starting at the DNS level. Perhaps for now both names
resolve to the same actual system (or load balancer, haproxy etc.) and
it does the work for both. But, when you decide to break one away from
the other for some reason, at least the hostnames used by your myriad
API users are unchanged.

Jeff

[Jurgens du Toit]

Further to this, I'm thinking of creating a web service that will act as both the HTML app and the API, depending on the Accept header sent.

Is this a good idea?

J

--
Jurgens du Toit
Cell: +27 83 511 7932
Website: http://jrgns.net

If people never did silly things, nothing intelligent would ever get done.
  - Ludwig Wittgenstein

[Greg Brail]

What if there is no Accept header sent? If I were running a quick test of your API to see what it can do then that's what I would do first...

--
Gregory Brail  |  Technology  |  Apigee

[Jurgens du Toit]

Good question. I was thinking of using other tells to determine what format is being requested, such as the presence of an extension, or the environment of the request.

So a request to http://my.webapp.com/clients.html will render in HTML

If the user agent is curl or wget, default to json, if it's a browser HTML.

Otherwise default to something that makes sense for the context of the app.

J

[Peter Williams]

On Wed, Apr 25, 2012 at 12:12 AM, Jurgens du Toit
<jurgens...@gmail.com> wrote:
> Further to this, I'm thinking of creating a web service that will act as
> both the HTML app and the API, depending on the Accept header sent.

I do this all the time and, in my experience, it works quite well. It
might make exploring the api a tad non-obvious for some people so just
make sure you show now to pass the appropriate accept header with
curl, etc in your docs. A downside of this approach is that it could
complicate a transition to having separate deployments of the HTML app
and the API.

Peter
barelyenough.org

[Carlos Eberhardt]

Default response type of XHTML? Browsers can render it, parsers can parse it. 

I think the challenge would be decomposing the services to something that makes sense as a web application. If you could do that successfully... 

Thanks,

Carlos

[Mike Kelly]

fwiw if you use hal+json, I'm going to be releasing an open source
browser (single page web app) for browsing an API directly. Here's a
screen shot of where it's at atm:

http://t.co/ai0OhGbE

Cheers,
Mike

--
Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123