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 https://github.com/ehearty/Swadl/issues/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 https://github.com/ehearty/Swadl/issues/2#issuecomment-147866798.

[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 https://github.com/ehearty/Swadl/issues/2#issuecomment-148096509.

[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 https://github.com/ehearty/Swadl/issues/2#issuecomment-148124329.

[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 https://github.com/ehearty/Swadl/issues/2#issuecomment-148645022.