Thanks to Kevin Marks suggestion and an upset stomach which made me blink in and out of sleep for three hours (I am still short 5 hours), I came up with a new design for the web service I was working on, a design which I am calling screen-based web service API. It's not REST so I figured the design approach calls for a different name and, since the approach is similar to the mainframe COBOL application screen scraping web services, the word screen makes sense.
The first cut of the web service API was of traditional RPC-based design. It was functional but none of my client's customers put it into production use. Many stories and lessons there.
The second cut was RESTish grocery bag-based design which I just spent three weeks implementing. Most of that three weeks was spent on eating my own dog food. By the last week, I was terrifyingly convinced that it would take more than a month for a customer to integrate the web service into their webapp. What I wanted was some where between one to three weeks.
With the screen-based API design, which I'll explain after eating it for a while, I think the target goal will be met with ease and the amount of details developers need to know will drop quite a bit, perhaps slicing the documentation by at least half.
Now I have only two problems:
- Convince my client into abandoning the second cut and waiting for the third.
- Whether or not to bill my client for the three hours of design work I've done while sleeping.