I am asked almost daily about guidelines to design a web service.
Well, instead of going to SOA, WS-* and so on. I am taking a different approach for the request, response and exception handling.
My approach is design the service as you would do your UI. Think about user experience (UX).
For example, think about filling a registration form of a website.
hat input fields would you put on screen?
On one hand you have the minimal set of data that you require. On the other hand you not want to have too much data that is not mandatory and will require exhaustive effort from your user.
What information would you plan to get with a search parameters?
This is even harder to decide. On one hand you want to provide as much information as possible. On the other hand to much information will be handled like the second page of google, never get there.
Until now it is rather trivial if you embrace the idea.
Now, what about exceptions? How would you want to get the error message when you fill that form on the internet?
Basically you have 2 alternatives:
1. Get a single error every submit and then fix field by field until the end of the form.
2. Get all the errors for the form data and fix the input in one go.
I prefer the 2nd alternative because the 1st is always annoying.
With service it is even better, sometimes the process behind the service is complex and I always hope that the service caller will know what to do with the detailed errors that I return from the service.
In a nutshell, if your service is a form you need to fill and you feel comfortable to use it, you have a winner.
Happy new year,