We help IT Professionals succeed at work.
Get Started

Best practice for extensive webservice API?

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?
//-- 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";
//-- 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

Watch Question
Project Manager / Technical Lead
This problem has been solved!
Unlock 2 Answers and 4 Comments.
See Answers
Why Experts Exchange?

Experts Exchange always has the answer, or at the least points me in the correct direction! It is like having another employee that is extremely experienced.

Jim Murphy
Programmer at Smart IT Solutions

When asked, what has been your best career decision?

Deciding to stick with EE.

Mohamed Asif
Technical Department Head

Being involved with EE helped me to grow personally and professionally.

Carl Webster
CTP, Sr Infrastructure Consultant
Ask ANY Question

Connect with Certified Experts to gain insight and support on specific technology challenges including:

  • Troubleshooting
  • Research
  • Professional Opinions
Did You Know?

We've partnered with two important charities to provide clean water and computer science education to those who need it most. READ MORE