Question

I’m planning an XML web service that takes an XML request and returns an XML response over HTTP. It’s not SOAP, and it’s not pure REST either – I think it might be best described as a POX (Plain Old XML) API. (More details towards the end of this post, if you’re interested, but I’m trying to keep my main question general.)

My experience with XML involves little more than DOM and SAX… I don’t have much of a clue about the sorts of toolkits that developers typically use to integrate their applications with third-party web services. But I want to make this web service as simple as possible for others to use.

I’ve made an XML Schema to describe what’s allowed in the XML request and the XML response. Straightforward enough, except I don’t know how well it will work with various toolkits. I understand that there are toolkits out there that can take an XML Schema and turn it into classes (e.g. for .Net or Java). A lot of the potential customers that I’ve spoken to are using .Net in some shape or form, so I suppose the .Net toolkits are the most relevant in this instance. (Although I definitely don’t want to make something .Net specific, I do want to try to make it as easy as possible for the typical customer to use this web service.)

So specifically I’m wondering about what I should do to make things easier for developers:

1. Should I have an XSD file for the request, and one for the response, or put them both together in one XSD file? Or should I split it up into, say, 3 XSD files: one for request-specific stuff, one for response-specific stuff, and one for shared types?
2. If an attribute can be a number between, say, -100 and +100, I can, and will, limit it in the XSD using minInclusive and maxInclusive, but should I define it as a byte or an integer or what (see types here)? A byte is big enough, but I have an unsubstantiated feeling that a byte might not play well with toolkits. Or perhaps it might cause problems if I later decide to change it to a short and expand the limits to, say, -200 and +200.
3. Are there any particular XSD constructs that are known to cause problems with toolkits, and that I should avoid if possible?
4. Is it actually a good idea to provide an XSD at all? Will it actually make things easier for people? (I figure it would, but best to check!)
5. At a later date I might want to update the XSD to introduce some new options. I figure I can do this carefully such that XML that was compatible with the old version will remain compatible with the new version. But will that totally screw things up for developers that have used toolkits and auto-generated code?
6. Is there anything else in particular that I should be aware of? Or am I asking all the wrong questions in the first place?! 😀

A little more info on what I’m trying to do (only if you want it):

I tried to keep my main question general, so that others would find it useful, but, in case it’s relevant, here’s a bit more information about what I’m trying to achieve, and what I’m planning.

I’m designing a web service that will calculate data on demand, for authorized clients only. A client request will consist of an XML specification of the data they want, along with authentication. My servers will calculate the data they asked for, and send it as an XML response.

I’ve never built a web service before, but I’ve spent quite a while looking into SOAP, REST, XML Schema, security, and a number of existing web services/APIs like Amazon SimpleDB, Flickr, and Netflix.

After much deliberation I’ve decided that:

1. SOAP isn’t right for this, because many of the clients will be small desktop apps, not big enterprise apps with toolkits for stuff like XML Signatures. Plus it sounds to me like SOAP might be an interoperability nightmare. Maybe I’ll add a SOAP option later, but ideally I’d avoid it altogether.
2. XML makes more sense than JSON because customers of this web service are more familiar with XML, and I can’t think of a use case that would involve a JavaScript client using the web service, so that obvious advantage of JSON isn’t relevant.
3. REST in its purest sense isn’t right for this, because this web service will be more activity oriented than resource oriented (this article helped me to see this distinction). To the dismay of any REST purists, I might call it a “REST API” for convenience, but really I think it might be best described as a POX API (Plain Old XML API). I’m trying not to focus too much on the terminology.
4. There’ll be an XML request and an XML response.
5. For security I’ll be using a system inspired by Amazon SimpleDB and OAuth. Basically I’m planning to take the XML request, convert it to a byte array, create a signature/MAC using HMAC-SHA1 or similar, and send the XML byte array and the signature/MAC byte array as HTTP POST parameters, Base-64 encoded. There’s more to it than that (public keys, private keys, timestamps, and nonces), but that’s the gist of it.

I’ve developed XML Schema for the request and the response, currently all just in one .xsd file, but I’m wondering about how best to structure things for compatibility and ease of use from various platforms/toolkits etc.

Answer 1

You’re actually over-thinking this. The idea behind web services is to function as an interface for consuming applications. In the end, it’s just some payload being sent from client to server over HTTP protocol.

Most of the issues you mention are related to building stub/proxy clients for the consuming application. .Net has Visual Studio and command-line wsdl.exe utilities, Java has Apache Axis2 and other tools, etc. The list goes on for every other language/platform you can dream up. I wouldn’t concern yourself too heavily with the details of these tools; they’re constantly changing, so keeping up can be a struggle.

To find the information you need, delve into worlds — write a .Net client, a Java client, a Python client, a Ruby client, etc. Find out what’s necessary to consume your service in those environments (if that’s really necessary.) Prioritize the list based on your customer set, or who you want to be your customer set.

As I’m sure you’ll discover, developers who are proficient in those environments will also know how to consume your service. If they’re a worthy part of your market, find out what they need from you in order to facilitate their access and usage.