5

I'm working in a corporation that has two products. One is a desktop application the other is a web-application. I'm in on the part as backend-engineer on the web-application. I design the web-interfaces. We use SOAP as the interface technology.

Now as the product develops there are lots of changes in the current not released version of the interface.

The web-application develops way faster than the desktop-app and we make a new interface-version only if we get live with it (means there is a customer-desktop-app that uses this interface-version). But now and then there are new use-cases that the desktop app should be able to handle. And we have to exchange new data so we extend the current version.

When we present the new interface to the desktop-developers (after lots of business-reviews) they always complain about the structure, naming and content of the scheme. They kind of refuse to work with it and there are a lot of meetings and unnecessary talk. Technologically its all fine, but it's like they are not on the same boat.

What would a best-case look like when I want a to define a soap interface that is accepted from developers and businessman alike?

I'm looking for a best-case-scenario how to handle this. I hope that when the idea of a working workflow does not come from me (the developer) it is easier for the businessman to accept it.

EDIT(@k3b follow up question):

they always complain about the structure, naming and content of the scheme

As the interface provider we define the structure. The desktop-developers complain about how we did structure the content. There are several ways it is possible and we choose the structure that is closest to the real-world. This does please the business mostly but 'offends' the developers. One of the most used arguments are that we "generate unnecessary work for them when there would be an easier way (from a developers view)".

In the technical-view I agree. We could make it easier. But due to the fact that the business can't read the XSDs and the provided api well enough we have to simplify it for them. So they can go an sell the data-interfaces to other business people.

When we make an interface that favors the dev's - the business won't be able to read it (I tried).

Sign
  • 2,643
SWiggels
  • 169
  • 5
  • 4
    Please note that requests for external resources are explicitly off-topic here (and, in fact, on any Stack Exchange site I'm active) so you might want to re-word your question a little as to avoid it being closed or down-voted. – 5gon12eder Sep 27 '16 at 06:50
  • can you give us an example of what "they always complain about the structure, naming and content of the scheme" mean? Is this a problem of coding style or of wrong business functionality? – k3b Sep 27 '16 at 11:55
  • If it's hard for your in-house developers, why would it be easy for your clients' developers? – HorusKol Sep 28 '16 at 06:58
  • Dear HorusKol the fun is that clients' developer usually have no problem in understanding the interfaces. They just generate all they want from the wsdl and look up the rest in the api. – SWiggels Sep 28 '16 at 07:17

2 Answers2

6

A recognizable scenario.

As you already have client side prototypes (at the minimum), make a (nice) client side API, and test code on a test database. That should remove the distraction created by the SOAP plumbing. Have a defined glossary of bussiness entities. Document business rules.

An interface change should be backwards compatible - is it not? A client side API may hide attributes, collect in one single parameter class several attributes, so the API remains solid.

Extensions for specific functionality could use the adapter / decorator pattern.

The problem is that they probably are nearer to the real-world business concepts than the IT. They might want new features, but certainly not the effort to upgrade on their own. And certainly not errors. So unit tests, documented test data and such are important.

However much will not be new.

  • A client API with test tools and the rest will give extra quality, help the client and cost you nothing if you are already into unit and integration testing. It will save you, when established.
Joop Eggen
  • 2,051
  • 12
  • 10
  • Many thanks for your answer. We use unit-tests and integration tests. I may have to do extra documentation as you suggested (glossary/business rules) for the business people to solve this side. The interface is backwards compatible and I use the adapter pattern and we offer an api-page. I guess I went in the right direction. I will make the api nicer and document the test-data to make it more transparent for the other desktop-developers. – SWiggels Sep 27 '16 at 09:17
  • Nice to see standards fullfilled. Take my answer with some salt though. I have seen both sides. And it always is a matter of too little substance in the formal communication, then ending in endless talks. Simply being able to deliver "this is what we deliver", "here is the short sample.code wich shows these input and output business information" upto migration patches, code detection. Having good explaining error messages, fail-fast helps too. If nothing helps, one needs channeling and prioritizing issues. But here it sounds more diffuse. – Joop Eggen Sep 27 '16 at 09:26
  • Thank you for the detailed answer. I have to look at our error-messages and check if they all still fit. – SWiggels Sep 27 '16 at 09:43
0

If it is SOAP, provide them a SOAP UI project with several test cases and requests that show how to call the service. That should be more than enough and will allow them to actually send requests and look at the responses prior to coding. This is a little less abstract than an XSD and will give everyone a sense of the request/response structure that is being used.

Names are just names. If they don't like the names it can be changed:

[DataMember(Name="YourAPIName")]
public string ThierClientName {get; set;}

So, I don't think that is a valid argument from them. If you are doing SOAP, try to avoid using attributes and use just elements instead as this will move them away from legacy serialization technologies. Keep the interfaces simple and concise.

If they are really in a hurry all they should need to do is point at the WSDL and have their client technology stack generate the code off the WSDL definition. Or they will manually code it themselves. Either method should only take a finite amount of time.

You could also include them as part of the design process. Perhaps they feel they are receiving a grenade being thrown over the wall. If they are involved up front and are allowed to dictate some of the interface perhaps they would be more receptive to it.

Jon Raynor
  • 11,421
  • I once provided a SOAP-UI Project with tests cases but we had then ~50 different schemes and had to update several structural issues (it was at the beginning of the project) so all the test-cases did not work anymore. I may should start doing these tests again. But thanks for bringing that back in my mind! PS: in the next iteration I try to let them do the most soap defining and and supervise it to defuse the change impact. – SWiggels Sep 28 '16 at 07:16