All:
A question for designers out there who wish to opine on best practices
or advise me about an upcoming issue: we have an essentially RPC web
service being considered for conversion to a RESTful one. Apologies for
the length of the post before it even begins:
The current SOAP web service, among other things, generates PDF reports
(using BIRT behind the scenes, although of course that could be swapped
out, which was the idea). A report can have arbitrarily many parameters
(and many have quite a few) that must be supplied. In addition, the
service performs a number of other functions are currently executed
within a single service call. For instance, the service may print the
generated document, keep it for later retrieval, or save it to a
database. It may retrieve a document from the database rather than
generating it.
At the moment, what the service does is governed by a DocumentMetadata
object:
public interface DocumentMetadata
{
String getDesignFilename();
String getAssociatedCaseId();
String getDocumentItemPageId();
String getTitleToSaveAs();
boolean isKeepAfterProcessing();
}
This allows the client to specify the name of the report file to use in
generation, the case to which the document should be associated (a
one-to-many relationship), the database ID of the document, the title to
save the document as, and whether or not to keep it available.
Another object (PrintJob) sent along details print parameters (printer
to use, number of copies, orientation, etc.).
The service uses these to decide what to do:
1. If the designFilename is supplied, a report is generated.
2. If the documentItemPageId is supplied, the report is retrieved from
the database.
3. If the titleToSaveAs is supplied, the report is saved to the database
with the appropriate title in addition to the bytes of the report itself
(all saved documents require titles).
4. If the report is saved to the database and the associatedCaseId is
supplied, a foreign-key reference to the case is inserted along with the
document record (documents may relate to cases or not [e.g., summaries
of daily activity relate to no specific case]).
5. If the keepAfterProcessing is set to true, the document is saved and
information about how to retrieve it is returned to the client.
6. If the print object is supplied (non-null), the document (however
obtained) is printed following the supplied parameters or sensible
defaults.
What is returned to the client is a ProcessingOutcome object:
public interface ProcessingOutcome
{
boolean isReportCreationSuccessful();
String getDocumentId();
String getDocumentItemId();
String getDocumentItemPageId();
boolean isPrintingSuccessful();
String getUrl();
String getUnc();
}
Most of this is obvious:
1. Whether report creation was successful (false if the report was
retrieved from the database)
2. The various database IDs associated with the document (don't even ask
- I didn't design the database, obviously)
3. Whether or not printing was successful (false if it was not
requested)
4. If the document was kept, a URL for retrieving it via HTTP and a UNC
reference for retrieving it via Windows Explorer et alia
So now the questions:
1. Can or should this service be converted to REST?
2. Can it be converted to REST as is, or should it be broken up into
smaller pieces (not sure the client would agree to that)?
3. Can REST handle the amount of data a GET request would necessarily
have to include?
Any ideas? Any tales of converting something like this and the ups and
downs you encountered?
Thanks in advance!
David Sills
