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?
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!
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.
-----Original Message----- From: api-craft@googlegroups.com [mailto:api-craft@googlegroups.com] On Behalf Of Jack Repenning Sent: Tuesday, April 17, 2012 3:20 PM To: api-craft@googlegroups.com Subject: Merging API and web app?
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?
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!
> 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.
> 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.
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
-----Original Message----- From: api-craft@googlegroups.com [mailto:api-craft@googlegroups.com] On Behalf Of Peter Williams Sent: Wednesday, April 18, 2012 10:10 AM To: api-craft@googlegroups.com Subject: Re: Merging API and web app?
On Tue, Apr 17, 2012 at 7:17 PM, Jack Repenning <repenning.j...@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.
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.
On Thu, Apr 19, 2012 at 11:44, Arlo Belshee <Arlo.Bels...@microsoft.com> wrote: > 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
> -----Original Message----- > From: api-craft@googlegroups.com [mailto:api-craft@googlegroups.com] On Behalf Of Peter Williams > Sent: Wednesday, April 18, 2012 10:10 AM > To: api-craft@googlegroups.com > Subject: Re: Merging API and web app?
> On Tue, Apr 17, 2012 at 7:17 PM, Jack Repenning <repenning.j...@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.
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.
On Sat, Apr 21, 2012 at 7:56 PM, Jeff Schmidt <jas...@gmail.com> wrote: > 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.
> 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
> On Sat, Apr 21, 2012 at 7:56 PM, Jeff Schmidt <jas...@gmail.com> wrote:
>> 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.
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.
On Wed, Apr 25, 2012 at 8:15 AM, Greg Brail <g...@apigee.com> wrote: > 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...
> On Tue, Apr 24, 2012 at 11:12 PM, Jurgens du Toit < > jurgens.dut...@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.
>> Is this a good idea?
>> J
>> On Sat, Apr 21, 2012 at 7:56 PM, Jeff Schmidt <jas...@gmail.com> wrote:
>>> 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.
<jurgens.dut...@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.
> 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...
> On Tue, Apr 24, 2012 at 11:12 PM, Jurgens du Toit <jurgens.dut...@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.
> Is this a good idea?
> J
> On Sat, Apr 21, 2012 at 7:56 PM, Jeff Schmidt <jas...@gmail.com> wrote: > 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.
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:
On Wed, Apr 25, 2012 at 2:55 PM, Peter Williams <pe...@barelyenough.org> wrote: > On Wed, Apr 25, 2012 at 12:12 AM, Jurgens du Toit > <jurgens.dut...@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.
