build HTTP client into swadl

[upachler]

Hi Elena,

Are there any plans to build a HTTP client into swadl? Swagger has one, which lets you try out the services you can document with it - it'd be great if swadl had something like this too; it would help with testing and my app devs would stop nagging me that "your APIs are so hard to call" ;-)

I'm no good with frontend webby stuff, but I can conribute some XSL if that helps.

Cheers,

Uwe

[ehearty]

Hi Uwe,

Adding an HTTP client is certainly doable, but I left it out because a lot
of APIs these days require authentication, and that seemed like a big can
of worms that I didn't feel like dealing with at the time.

One of the things that I didn't like about Swagger (when my company was
evaluating it) was what looked like the inability to turn those calls off.
For example, we didn't want to expose all of the calls to clients that
couldn't authenticate.

Seems like a useful feature, though, so long as there's a flag to turn it
on and off. I'll put it on the roadmap.

Thanks,
Elena.

On Mon, Oct 12, 2015 at 2:45 AM, upachler [email protected] wrote:

Hi Elena,

Are there any plans to build a HTTP client into swadl? Swagger has one,
which lets you try out the services you can document with it - it'd be
great if swadl had something like this too; it would help with testing and
my app devs would stop nagging me that "your APIs are so hard to call" ;-)

I'm no good with frontend webby stuff, but I can conribute some XSL if
that helps.

Cheers,

Uwe

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

[upachler]

Hi Elena,

Glad to read that a HTTP client is on the cards!

Such a client could build on enrichments in the WADL source. You'd simply add elements from another namespace as extensions, like authentication per resource:

...
<w:resource path='foo'>
   <x:authentication type='basic' realm='myrealm'/>
   ...

Another reason for extensions may be message body examples to display in the swadl documentation that users may use as a starting point when using the client:

..
<w:resource path='foo'>
  <w:method name='PUT'>
     <w:request>
        <w:representation mediaType='application/xml' element='b:book'>
           <x:example>

              <!-- we embed the example XML here - this may also in a different form, 
              depending on the media type -->
              <b:book name='Macbeth' author='W. Shakespeare'>
                <b:chapter name='prolougue'/>
                ...
              <b:book/>

            </x:example>

Both of these extensions could then be picked up by the a swadl-generated client.

Cheers,
Uwe

[ehearty]

I think the first pass will assume no authentication or enrichments, and
just provide a very basic client. Then it should be easy to build upon that
with future iterations.

Thanks,
Elena.

On Tue, Oct 13, 2015 at 6:04 PM, upachler [email protected] wrote:

Hi Elena,

Glad to read that a HTTP client is on the cards!

Such a client could build on enrichments in the WADL source. You'd simply
add elements from another namespace as extensions, like authentication per
resource:

...
<w:resource path='foo'>
<x:authentication type='basic' realm='myrealm'/>
...

Another reason for extensions may be message body examples to display in
the swadl documentation that users may use as a starting point when using
the client:

..
<w:resource path='foo'>
<w:method name='PUT'>
<w:request>
<w:representation mediaType='application/xml' element='b:book'>
<x:example>

          <!-- we embed the example XML here - this may also in a different form,               depending on the media type -->
          <b:book name='Macbeth' author='W. Shakespeare'>
            <b:chapter name='prolougue'/>
            ...
          <b:book/>

        </x:example>

Both of these extensions could then be picked up by the a swadl-generated
client.

Cheers,
Uwe

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

[upachler]

Sounds great! While I'm not too good with all that JavaScript/Frontendy stuff, I may be of help in the second stage with these enrichments, or simply with testing.

The main reason for me asking about swadl enhancements is a pet project I'm currently working on: It aims at bringing all aspects of W*DL contract-first development into one toolchain, quite similar to what swagger does. The aim is to generate clients & server interfaces on various platforms, as well as documentation (that's where swadl comes in).

The toolchain may simply generate examples from XML Schema complexTypes found in the WADL's grammar, and put them into a 'normalized' WADL, where swadl can pick them up.

So I'm looking forward to the client functionality; let me know if I can assist.

Cheers,
Uwe

[ehearty]

Well, full disclaimer: I'm not a front-end dev either. I just like to dick
around with this stuff :)

My big concern about putting a ton of time into this project is the WADL
seems to have fallen out of favor...and I'm honestly not sure why. Seems a
lot easier than messing around with Swagger's custom annotations.

Do you have an extended WADL set up for your project? The one I set up a
while back generated the schemas for the complex types quite nicely. I
didn't save it off, however, and now the Jersey documentation on how to set
up the extended WADL appears to be defunct. But you have any sample files
being generated from your web service (wadl + xsd), send them my way and
I'd be happy to take a look at them.

Again, I don't know how much time I'm going to have to devote to a client,
but I'll try to get something basic started, and I can always hand it off
to you once it's underway.

Thanks!
Elena.

On Wed, Oct 14, 2015 at 11:54 AM, upachler [email protected] wrote:

Sounds great! While I'm not too good with all that JavaScript/Frontendy
stuff, I may be of help in the second stage with these enrichments, or
simply with testing.

The main reason for me asking about swadl enhancements is a pet project
I'm currently working on: It aims at bringing all aspects of W*DL
contract-first development into one toolchain, quite similar to what
swagger does. The aim is to generate clients & server interfaces on various
platforms, as well as documentation (that's where swadl comes in).

The toolchain may simply generate examples from XML Schema complexTypes
found in the WADL's grammar, and put them into a 'normalized' WADL, where
swadl can pick them up.

So I'm looking forward to the client functionality; let me know if I can
assist.

Cheers,
Uwe

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

[upachler]

WADL seems to have fallen out of favor...and I'm honestly not sure why

Yep, I see that here as well. I guess it has to do with the fact it's based on XML, where people nowadays favor JSON, and that even though the tools are all there (CXF, JAXB/XJC, etc.), they're not well integrated to form a single toolchain.
I've got a ton of experience writing tools and code generators, so I thought I give that a go and put all the pieces together in a way so that you get the swagger toolchain for WADL, in short ;-)

Do you have an extended WADL set up for your project? [..]

In short, no. I don't use Jersey, and I generally won't rely on framework-generated WADL at runtime. I usually work contract first, so I start with a hand-written WADL and XSD.
This way, I can generate server and client interfaces at build time and then implement them server-side, or get clients generated at build time (quite useful on mobile platforms like iOS) and call them from app code. I found that very useful when I need to integrate cross platform (iOS/Android app to Java Server), because this way there is only a single source of truth (everything flows from the WADL/XSD contract).
The downside is the complex tool setup that's required to get all this working (even with Maven, which I'm using extensively).
So this was another motivation to start working on the toolchain project.

If you're interested, hook up with me on bitbucket. It's currently in a private repo, but I'd grant you access so you can see what's there.

Cheers,
Uwe

[ehearty]

I was messing around with the project and got some basic requests going.

Could you send me a sample WADL and XSD files that you feel represent your
use case? That way, I'll know whether or not I have the proper
functionality covered.

And I can't promise a timeline, but I'll create a branch, update it with my
revisions, and you can jump in if you think things are moving too slow.
Even if you're not familiar with javascript, I seriously doubt you'll have
any trouble following what's going on in the code.

Thanks,
Elena.

On Wed, Oct 14, 2015 at 1:21 PM, upachler [email protected] wrote:

WADL seems to have fallen out of favor...and I'm honestly not sure why

Yep, I see that here as well. I guess it has to do with the fact it's
based on XML, where people nowadays favor JSON, and that even though the
tools are all there (CXF, JAXB/XJC, etc.), they're not well integrated to
form a single toolchain.
I've got a ton of experience writing tools and code generators, so I
thought I give that a go and put all the pieces together in a way so that
you get the swagger toolchain for WADL, in short ;-)

Do you have an extended WADL set up for your project? [..]

In short, no. I don't use Jersey, and I generally won't rely on
framework-generated WADL at runtime. I usually work contract first, so I
start with a hand-written WADL and XSD.
This way, I can generate server and client interfaces at build time and
then implement them server-side, or get clients generated at build time
(quite useful on mobile platforms like iOS) and call them from app code. I
found that very useful when I need to integrate cross platform (iOS/Android
app to Java Server), because this way there is only a single source of
truth (everything flows from the WADL/XSD contract).
The downside is the complex tool setup that's required to get all this
working (even with Maven, which I'm using extensively).
So this was another motivation to start working on the toolchain project.

If you're interested, hook up with me on bitbucket
https://bitbucket.org/uwe_pachler/. It's currently in a private repo,
but I'd grant you access so you can see what's there.

Cheers,
Uwe

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

[upachler]

Hi Elena,

I'll have to dig a bit to come up with a WADL for testing, as most of the stuff I've done in the field is closed source. So it'll be over the weekend (I might even craft a new one, we'll see).
How can I send that to you? You have no email address on your account on github, and there appears to be no way to send messages over that platform.
As none of us wants to publicly post their email addresses, we could get in touch over bitbucket, like I suggested earlier. It allows sending private messages to users.

Cheers,
Uwe

[ehearty]

Eh, I'll risk it. Shoot me the sample files at elena.hearty(at)gmail(dot)com

Thanks,
Elena.

On Fri, Oct 16, 2015 at 4:05 AM, upachler [email protected] wrote:

Hi Elena,

I'll have to dig a bit to come up with a WADL for testing, as most of the
stuff I've done in the field is closed source. So it'll be over the weekend
(I might even craft a new one, we'll see).
How can I send that to you? You have no email address on your account on
github, and there appears to be no way to send messages over that platform.
As none of us wants to publicly post their email addresses, we could get
in touch over bitbucket, like I suggested earlier. It allows sending
private messages to users.

Cheers,
Uwe

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