You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@cxf.apache.org by Phillip Rhodes <sp...@rhoderunner.com> on 2008/12/10 01:25:55 UTC
Web Service api design (pass simple parameters or pojo)?
This is a design issue that I continue to stumble across....
I am at a crossroads between passing instances of my pojo objects as
data containers VS. a long list of parameters. Having worked with
both cases, the long list of parameters gets very unmanageable. (What
was that 10th parameter?....) Another option is to pass a map of
parameters, but that is also problematic since you have all kinds of
code to add and process the map.
That leaves me with passing my pojo's as a data container to my web
service. What are the drawbacks of such a design? Or Is the time
invested in a map of parameters worth it?
The API that I am designing is pretty much like a JCR repository, but
one that provides some additional services around images and
searching, and most importantly, super fast.
Thank you for your time.
Phillip
Re: Web Service api design (pass simple parameters or pojo)?
Posted by Phillip Rhodes <sp...@rhoderunner.com>.
Wow! Awesome points.
I appreciate your advice. I think the cool thing is that you
reminded me is that I can design complex types to represent my
messages so that can isolate my internal application changes from my
api users. Back to the IDE for me;)
Thanks again,
Phillip
On Dec 10, 2008, at 2:15 AM, Christian Schneider wrote:
> Hi Philip,
>
> I have some suggestions for you. First you should not generate the
> wsdl from your implementation classes. We did this approach in the
> start of our SOA. The problem is that when you change the version of
> your service framework you can end up with a slighty different wsdl.
> So you change your service contract when you only wanted to change
> an implementation detail. I have written a howto on generating the
> wsdl from java definitions and then generate the implementation
> stubs from it: http://cwiki.apache.org/CXF20DOC/defining-contract-first-webservices-with-wsdl-generation-from-java.html
>
> The second thing is to apply best practices from API design to your
> service contract. Imagine many people are using your service
> contract. That means they depend on the contract staying stable. If
> you use your pojos as a service contract it means that any change
> you make to them will break your service contract. So I would
> suggest to define the contract separately from your pojos and do a
> mapping from the contract data elements to the inner pojos. If the
> pojos you are talking about are already api quality then you could
> use them in the contract. But then you still will have the problem
> above.
> I found a nice article about contract design: http://www.infoq.com/articles/contract-versioning-comp2
>
> The last thing is I would use complex type style for the data. It is
> easier to understand than parameter lists and more type safe then
> maps. In complex types you can also mark elements optional so people
> do not always have to set all elements.
>
> Hope I could help a little.
>
> Greetings
>
> Christian
>
>
> Phillip Rhodes schrieb:
>> This is a design issue that I continue to stumble across....
>>
>> I am at a crossroads between passing instances of my pojo objects
>> as data containers VS. a long list of parameters. Having worked
>> with both cases, the long list of parameters gets very
>> unmanageable. (What was that 10th parameter?....) Another option
>> is to pass a map of parameters, but that is also problematic since
>> you have all kinds of code to add and process the map.
>>
>> That leaves me with passing my pojo's as a data container to my web
>> service. What are the drawbacks of such a design? Or Is the time
>> invested in a map of parameters worth it?
>>
>> The API that I am designing is pretty much like a JCR repository,
>> but one that provides some additional services around images and
>> searching, and most importantly, super fast.
>>
>>
>> Thank you for your time.
>>
>> Phillip
>>
>
>
> --
>
> Christian Schneider
> ---
> http://www.liquid-reality.de
>
Re: Web Service api design (pass simple parameters or pojo)?
Posted by Christian Schneider <ch...@die-schneider.net>.
Hi Philip,
I have some suggestions for you. First you should not generate the wsdl
from your implementation classes. We did this approach in the start of
our SOA. The problem is that when you change the version of your service
framework you can end up with a slighty different wsdl. So you change
your service contract when you only wanted to change an implementation
detail. I have written a howto on generating the wsdl from java
definitions and then generate the implementation stubs from it:
http://cwiki.apache.org/CXF20DOC/defining-contract-first-webservices-with-wsdl-generation-from-java.html
The second thing is to apply best practices from API design to your
service contract. Imagine many people are using your service contract.
That means they depend on the contract staying stable. If you use your
pojos as a service contract it means that any change you make to them
will break your service contract. So I would suggest to define the
contract separately from your pojos and do a mapping from the contract
data elements to the inner pojos. If the pojos you are talking about are
already api quality then you could use them in the contract. But then
you still will have the problem above.
I found a nice article about contract design:
http://www.infoq.com/articles/contract-versioning-comp2
The last thing is I would use complex type style for the data. It is
easier to understand than parameter lists and more type safe then maps.
In complex types you can also mark elements optional so people do not
always have to set all elements.
Hope I could help a little.
Greetings
Christian
Phillip Rhodes schrieb:
> This is a design issue that I continue to stumble across....
>
> I am at a crossroads between passing instances of my pojo objects as
> data containers VS. a long list of parameters. Having worked with
> both cases, the long list of parameters gets very unmanageable. (What
> was that 10th parameter?....) Another option is to pass a map of
> parameters, but that is also problematic since you have all kinds of
> code to add and process the map.
>
> That leaves me with passing my pojo's as a data container to my web
> service. What are the drawbacks of such a design? Or Is the time
> invested in a map of parameters worth it?
>
> The API that I am designing is pretty much like a JCR repository, but
> one that provides some additional services around images and
> searching, and most importantly, super fast.
>
>
> Thank you for your time.
>
> Phillip
>
--
Christian Schneider
---
http://www.liquid-reality.de