betfair/cougar

New transport for Swagger Spec

jorgemsrs opened this issue · 8 comments

jorgemsrs commented

Swagger is a somewhat new transport specification for building rich web api's. It is an aproximation of what wadl tried to be and arguably failed.

Some players are already supporting swagger namely apigee and recently thoughtworks also mentioned it in their monthly analysis.

Benefits over the existing data exchange transports are the ability to generate documentation from the spec and restful oriented bindings for building apis for the greater web audience.
It also boosts a ui for generating the interfaces and a codegen tool possible to be integrated in the cougar-codegen module. See references for greater detail.

Additional references:

eswdd commented

I'm not sure if this offers anything for Cougar.

It is already possible to generate documentation from BSIDL although we did
forget to release this when we open sourced Cougar. This could be rectified.

Cougar used to support REST but we took it out as it was felt REST is not a
good fit for the style of service/interface being built on Cougar. I feel
reintroduction would either be halfhearted as we would use a sufficiently
limited REST as to be indistinguishable from rpc or it would overcomplicate
our other transports in order to maintain transport independence.
On 10 Nov 2014 09:33, "Jorge Silva" notifications@github.com wrote:

Swagger is a somewhat new transport specification for building rich web
api's. It is an aproximation of what wadl tried to be and arguably failed.

Some players are already supporting swagger namely apigee
https://apigee.com/providers and recently thoughtworks also mentioned
it in their monthly analysis
http://www.thoughtworks.com/radar/tools/swagger.

Benefits over the existing data exchange transports are the ability to
generate documentation from the spec and restful oriented bindings for
building apis for the greater web audience.
It also boosts a ui for generating the interfaces and a codegen tool
possible to be integrated in the cougar-codegen module. See references for
greater detail.

Additional references:

—
Reply to this email directly or view it on GitHub
#88.

jorgemsrs commented

It brings standardisation for service producers and interoperability for service consumers.

I may be reading this wrong but the fact that cougar is made available to the dev community also means it should strive to reach for a reasonable diverse audience. In the real world bsidl ends up being a very opinionated contract with no benefits for consumers in languages other than jvm oriented ones with java interoperability.
By offering a transport which provides cheap client generation for a myriad of languages we're in fact walking towards making cougar a more amenable machine for creating accessible services - plus all the benefits cougar boosts already as a rpc.

Swagger makes use of the entire http spec providing for full rest capability.

Have your say :):

eswdd commented

BSIDL serves a different set of requirements to Swagger specs, namely
supporting more than just HTTP.

How do you suggest we adopt Swagger?

We can't replace BSIDL with Swagger AFAICS. We can't generate BSIDL from
Swagger I don't think.

This leaves generating Swagger from BSIDL, which means we likely won't use
the full range of REST so it matters not that Swagger supports full REST -
just that we can fully map BSIDL defined RPC to Swagger.

As you say, this opens up a range of clients for interoperability with
other languages/stacks - so yes there is potential for benefit. Whether we
can get sufficient hooks to properly integrate a Swagger transport will be
interesting.
On 11 Nov 2014 11:03, "Jorge Silva" notifications@github.com wrote:

It brings standardisation for service producers and interoperability for
service consumers.

I may be reading this wrong but the fact that cougar is made available to
the dev community also means it should strive to reach for a reasonable
diverse audience. In the real world bsidl ends up being a very opinionated
contract with no benefits for consumers in languages other than jvm
oriented ones with java interoperability.
By offering a transport which provides cheap client generation for a
myriad of languages we're in fact walking towards making cougar a more
amenable machine for creating accessible services - plus all the benefits
cougar boosts already as a rpc.

Swagger makes use of the entire http spec providing for full rest
capability.

Have your say :):

—
Reply to this email directly or view it on GitHub
#88 (comment).

eswdd commented

Regarding BSIDL and jvm oriented languages: "no benefits for consumers in languages other than jvm oriented ones with java interoperability" - that is an absolute fallacy.

BSIDL is merely a description of an interface, and clients could be implemented in any language. I know of clients that exist in 3 languages: Java, c#, Javascript - unfortunately only the Java ones have been open sourced, but it doesn't mean that they couldn't be or could not exist.

richardqd commented

To that I'd add Python too

On 12 November 2014 12:31, Simon Matic Langford notifications@github.com
wrote:

Regarding BSIDL and jvm oriented languages: "no benefits for consumers in
languages other than jvm oriented ones with java interoperability" - that
is an absolute fallacy.

BSIDL is merely a description of an interface, and clients could be
implemented in any language. I know of clients that exist in 3 languages:
Java, c#, Javascript - unfortunately only the Java ones have been open
sourced, but it doesn't mean that they couldn't be or could not exist.

—
Reply to this email directly or view it on GitHub
#88 (comment).

jorgemsrs commented

I see swagger as another transport. So the workflow for someone building a cougar service upon swagger would be 1) create the interface document 2) use the code gen to translate it to java syntax 3) implement logic. So in my view it would be a choice of the service creator wether to use bsidl and/or swagger.

I see no touching points between bsidl and swagger. they are in effect 2 notations which serve different purposes.

The fact that any cougar operated via tcp means it can have consumers built in virtually any modern stdlib. My point with BSIDL being made "for consumers in languages other than jvm oriented ones with java interoperability" was that the current code generator only knows how to create java code. swagger already has this point covered hence little work would have to be done.

I may have given the impression that swagger would be a competing interface representation but that was not my idea. The main goal is to keep possibilities open.

eswdd commented

Your last paragraph seems to say the opposite of the first.

In order to provide true transport independence then everything needs to be
defined by one master interface definition. This is a core Cougar principle.

So a swagger transport which has it's own seperate interface definition
language is not an option.
On 12 Nov 2014 23:49, "Jorge Silva" notifications@github.com wrote:

I see swagger as another transport. So the workflow for someone building a
cougar service upon swagger would be 1) create the interface document 2)
use the code gen to translate it to java syntax 3) implement logic. So in
my view it would be a choice of the service creator wether to use bsidl
and/or swagger.

I see no touching points between bsidl and swagger. they are in effect 2
notations which serve different purposes.

The fact that any cougar operated via tcp means it can have consumers
built in virtually any modern stdlib. My point with BSIDL being made "for
consumers in languages other than jvm oriented ones with java
interoperability" was that the current code generator only knows how to
create java code. swagger already has this point covered hence little work
would have to be done.

I may have given the impression that swagger would be a competing
interface representation but that was not my idea. The main goal is to keep
possibilities open.

—
Reply to this email directly or view it on GitHub
#88 (comment).

jorgemsrs commented

yeah... so I'm challenging the usefulness of bsidl for rest apis. it may be the case i'm mixing up what cougar tries to be with what i wanted it to be :)
if a rest capable transport is not a terrain cougar is keen to step then i'm completely happy to consider this issue rejected based on the given rationale.

Thanks for the discussion.