?
Solved

Best practice for extensive webservice API?

Posted on 2009-10-15
4
Medium Priority
?
1,297 Views
Last Modified: 2013-11-18
I'm building a SOAP webservice API to allow our customers to integrate their external apps with our systems. This requires the webservice(s) to have a lot of operations, and many different .NET classes to serialize.

What I have done so far is split the API into multiple webservices (.asmx files using VS.NET).

- PersonHandler.asmx
- CompanyHandler.asmx
- ActivityHandler.asmx
- etc.

This way the names of the operations can be a bit shorter (e.g. CompanyHandler.Save(...) instead of SuperHandler.SaveCompany(...)) and the actual files becomes more manageable when developing the API, since I don't need a 100'000 line file with all the code.

To make the parameterlists and return values of the service easy to use I have made a set of classes which act as simple data holders with no methods.

- Company
- Person
- Activity
- etc.

The problem arises when I make a sample client (in my case also in .NET).

When I add a reference to the webservice (using VS.NET or wsdl.exe) the data holder classes are auto-generated for each service that references them (as part of the WS proxy/wrapper).
So if both the PersonHandler and CompanyHandler uses a Person object in a return or parameter value it causes problems. If the proxies are generated in the same namespace there is an obvious problem with an "ambigious reference" and if the are created in seperate namespaces it makes the client app unnecessarily complicated and means that you have two 100% identitical classes in two different namespaces (so you can't e.g. use the Person class returned from CompanyHandler.GetPersonsWorkingAtCompany(...) to call PersonHandler.SavePerson(...)).

See the included code section for an example which illustrates the problem.

Any suggestions?
//
// FICTITIOUS EXAMPLES OF SAMPLE CLIENT
//
 
//-- Example 1 - Ambigious reference problem --
 
//Will not compile. "Person" is an ambigious reference since it is generated both for the PersonHandler and the CompanyHandler webservice proxy
 
int companyId = 32;
CompanyHandler companyHandler = new CompanyHandler();
PersonHandler personHandler = new PersonHandler();
 
Person[] personsForCompany companyHandler.GetPersonsWorkingAtCompany(companyId);
Person somePerson = personsForCompany[0];
somePerson.Name = "James Brown";
somePerson.Email = "james@brown.org";
 
personHandler.SavePerson(somePerson);
 
//-- Example 2 - Using namespaces which cause "class mismatch" --
 
//Will not compile. We can not call SavePerson with the somePerson object since it is another "Person" class than the one returned by GetPersonsForCompany
 
int companyId = 32;
Company.CompanyHandler companyHandler = new Company.CompanyHandler();
Person.PersonHandler personHandler = new Person.PersonHandler();
 
Company.Person[] personsForCompany companyHandler.GetPersonsWorkingAtCompany(companyId);
Company.Person somePerson = personsForCompany[0];
somePerson.Name = "James Brown";
somePerson.Email = "james@brown.org";
 
personHandler.SavePerson(somePerson); //will not compile, somePerson is wrong class for SavePerson even though they are based on the same class in the code for the webservice that is called

Open in new window

0
Comment
Question by:subsero
  • 3
4 Comments
 
LVL 18

Accepted Solution

by:
DarrenD earned 2000 total points
ID: 25578773
Hi,

As far as I know this is by deisgn and I'm not sure there is much you can do. You could look into createing a seperate dll with all of the types and have each client add this to each client. You might just be able to use an interface but I'm not sure.

If you change from Web Services to WCF and Add Service Reference instead there is an option to Reuse types when you are adding the service using the advanced options.

Hope this helps,

Darren
0
 
LVL 18

Assisted Solution

by:DarrenD
DarrenD earned 2000 total points
ID: 25578862
Hi again,

Here are some links that might help if you haven't already seen them:

http://msdn.microsoft.com/en-us/library/aa480505.aspx

http://www.developerfusion.com/article/5155/web-services-interoperability-between-j2ee-and-net-part-3/3/

http://bytes.com/topic/net/answers/428573-web-service-references-namespace-problem

If you do a search in google for 'WCF Proxy Types' you will find some WCF solutions to your problem.

Cheers,

Darren
0
 

Author Comment

by:subsero
ID: 25588949
Hi Darren,
No, I had not found those links. I tried googling all sorts of word-combos, but they all drowned in "how to set up your first SOAP WS" articles.
"creating a seperate dll"
I also briefly considered that. But I would really rather not add additional plumbing and complexity to the client end.
"use an interface"
I'm fairly sure the ".NET to SOAP XML" serialization will strip that info away. I might give it a try though - just to make sure.
"change from Web Services to WCF"
That does in fact solve it (combined with setting specific namespace on the serialization attribute.
But I need the API to be easy for the client developers to use, even if they do not have much experience with WS-tech (also I would imagine that many WS-enabled programming environments are lacking such a feature).
I think I will try to change the services so the classes are only used in one service, since that would save me all kinds of trouble keeping things up to date, and explaning the issue to client programmers.
Thanks for your help. At least now I know that I'm not missing some obvious solution and what my work-around options are.
Best regards,
Torben
0
 
LVL 18

Expert Comment

by:DarrenD
ID: 25589398
Hi Torben,

Glad I could be on some help.

I agree with you, the final solution you stated is the one I use most frequently.

Even in WCF I just try to keep as many classes in one place but it is a pain if you have lots of operations.

Cheers,

Darren
0

Featured Post

Independent Software Vendors: We Want Your Opinion

We value your feedback.

Take our survey and automatically be enter to win anyone of the following:
Yeti Cooler, Amazon eGift Card, and Movie eGift Card!

Question has a verified solution.

If you are experiencing a similar issue, please ask a related question

Styling your websites can become very complex. Here I'll show how SASS can help you better organize, maintain and reuse your CSS code.
Real-time is more about the business, not the technology. In day-to-day life, to make real-time decisions like buying or investing, business needs the latest information(e.g. Gold Rate/Stock Rate). Unlike traditional days, you need not wait for a fe…
Viewers will learn about if statements in Java and their use The if statement: The condition required to create an if statement: Variations of if statements: An example using if statements:
This tutorial will teach you the core code needed to finalize the addition of a watermark to your image. The viewer will use a small PHP class to learn and create a watermark.
Suggested Courses

750 members asked questions and received personalized solutions in the past 7 days.

Join the community of 500,000 technology professionals and ask your questions.

Join & Ask a Question