Hi On Mon, Jun 27, 2011 at 3:53 PM, David Sills <[email protected]> wrote: > 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?
I don't see immediate issues which would prevent it from being converted > 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)? Here are some observations. I'd avoid specifying an id upfront and let server allocate it for new PDFs. This can minimize a number of parameters. LIkewise, rather than 'leaking' a DB id, return opaque URI which will protect the consumer from the likely DB changes which may follow. You can get it split in two pieces, one (controller) will deal with DB (via indirection if needed), etc, and then you can get another component, possibly not even JAX-RS one, which will specifically handle the conversion of in Data into PDF. When consumer requests a new PDF the controller can also do some preparation work and redirect the consumer to a dedicated resource which will provide the actual PDF. This will make the experience smoother a bit for a client. Supporting multipart/form-data should also help with the browser asking the user where PDF needs to be saved... > 3. Can REST handle the amount of data a GET request would necessarily > have to include? > If one have so many input parameters that they can't fit into GET query then it's a sign the refactoring of the service URI space is really needed. Cheers, Sergey > Any ideas? Any tales of converting something like this and the ups and > downs you encountered? > > Thanks in advance! > > David Sills > > -- Sergey Beryozkin Application Integration Division of Talend http://sberyozkin.blogspot.com
