Bob Balaban's Blog


    Bob Balaban


    Domino Web Services: What if..... SOAP? or REST? (or both?)

    Bob Balaban  August 20 2007 06:11:24 PM
    Greetings, Geeks!

    I wrote a bit on this topic here in this blog a while back -->, but now I'm ready to explore it a little deeper, and I want YOUR feedback.

    Why now? Why deeper? Well, my colleague Steve Nikopoulos was kind enough to lend me a book, "RESTful Web Services", by Leonard Richardson and Sam Ruby (O'Reilly Media, 2007).

    Somewhere around Chapter 3, I actually got inspired to go looking for an interesting (public) RESTful Web Service. Since I'd done some writing and demo-ing about the SOAP-based Web Services a few years ago, and since I had heard that they'd since published some RESTful interfaces, I went looking there.

    Within 15 minutes, I had registered for an access key (you use it on all the calls, so they know who's touching their server), read a bit of the online doc, and tried out my first RESTful WS call:


    Go ahead, try it (go register for an ID first)! You'll get back a ton of XML describing a bunch of books written by (or narrated by, as it turns out), by an actor named Bob Balaban, and one book written by......(ta da!) ME. It was really easy, I just assembled the URL based on the doc using NotePad, then pasted it into my browser, and (as they say in France, Québec and Guadaloupe) Voilà!

    So, I've been pondering the future of Web Services in Notes/Domino. I've done a lot of work with the (now I guess we can call it "traditional") SOAP-based Web Services, and, while there are some limitations there, I generally think that when you combine the technology with appropriate tools, it's pretty easy to use, and provides great RPC functionality. But it's not the best choice for everyone, all the time.

    I thought I'd do a brief side-by-side pros & cons thing, then open it up for your feedback.

    SOAP Pros

    You can use many different tools (IBM RAD, Microsoft Visual Studio, lots more) to pull in  a WSDL file and generate a SOAP client proxy class in the language of your choice. The proxy class "looks" just like the interface of the service itself. You create an instance, invoke its methods, and it (the proxy class) figures out how to serialize all the inputs into SOAP XML format, and send it over HTTP to the server hosting the service (all of this info is contained in the WSDL description, in (of course) XML format).

    The other big advantage is that, when the SOAP answer comes back (and it can be complex data types), you don't have to lift a finger to parse the XML response, the proxy class does it for you. Comples data types (for both input and output) are represented as objects in your target language (e.g., Java classes), so if you're comfortable programming in that language, it looks and feels just like regular old language object oriented programming, rather simple.

    SOAP Cons

    The biggest drawback in this paradigm is that it's hard to do  anything on the fly. You have to pre-generate the client proxy (the Web Service consumer code), and (depending on the complexity of the WSDL description of the service) you might end up with dozens of objects (representing nested complex data types, etc.) to deal with. There's also some runtime overhead inherent in all of the generated code you execute on every call, and debugging can be a big pain.

    REST Pros

    A "Service" invoked via URL certainly seems conceptually simpler. There are really only 4 "methods" to figure out, the HTTP ones: GET, PUT, POST, DELETE (there are a couple more, but they're not often used). In practice, I suspect, as with the example above, you really end up tacking on a bunch of URL parameters to get the service to do exactly what you want, effectively expanding the number of methods in use to, well, as many as you (or the service provider) want.

    URL "commands" can easily be build on the fly (they're just strings), and virtually all programming languages these days have robust HTTP class libraries and XML parsing functionality readily available.  

    Plus, it's "just HTTP"! (or HTTPS, if you want to use SSL). The REST "style" implies that you address a resource of some kind with a URL/URI, specify a "method" and maybe some options, and you expect the result back (if any) in XML as well, possibly containing additional links that you might (or might not) want to follow. The book query at the beginning of this (now rather long) post, for example, returns some XML with embedded links, one for each discovered book, leading to the book's page on the site. Simple!

    REST turns out to be rather AJAX-friendly, because you don't get ALL the data at once. You can pull back (if things are set up right) enough data to paint a screen (or a part thereof), and not waste time reading and caching a bunch of data you might never need.

    REST Cons

    There are, I think, actually a few drawbacks here. One is that you need to understand the data schemas involved in each Web Service (as opposed to understanding an object model in the SOAP case). You end up doing a fair amount of XML parsing to pull out the results you want from what might be a rather complex result set. The other thing about REST-style programming that concerns me is that it's gotta be true that the client is going to be making a lot of extra trips to the server, at least in cases where you want to fetch a lot of data.

    Because the REST style implicitly results in XML results which contain links, you're going to (at least sometimes) be following (some of) those links. It's great that this setup yields great flexibility, it supports very dynamic UI interaction, you get the next hunk of data only when you need it, or not at all. But, more trips to the server means extra load on the server (remember: the server maintains no context from query to query, so EVERY URL must be processed from scratch every time), and extra load on the network. We worry about stuff like that.

    So, for those of you who have stuck with me thus far, a couple of questions:
       1) Do you buy my analysis of pros and cons?

       2) I think we (Lotus) pretty much have to implement some RESTful interfaces to support AJAX style access to Domino based Web apps. Do you agree?

       3) If we do that, will you use it?

      4) If we don't do it (right away), what will you use instead? (Remember, we already have Java and LotusScript based WS provider/consumer functionality in v8.0)

    Thanks! ttys!

    1Nathan T. Freeman  08/19/2007 8:06:17 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    "virtually all programming languages these days have robust HTTP class libraries"

    I can think of one language very popular for your reading audience that lacks robust HTTP class libraries. :-(

    2Andrew Price  08/19/2007 8:10:28 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    Hiya Bob,

    Thanks for explaining REST I didn't know what it was and had actually assumed that is how sane people would do this function -- hence my bafflement at SOAP which gives every appearance of being an unmitigated PIA designed by computer scientists rather than programmers.

    I keep a fairly close eye on freshmeat and there is a lot of RESTful stuff appearing there -- always a key signal imo.

    So, I concur with your analysis. REST tools are essential; SOAP tools less so (no doubt big IT shops will be keen on it).

    Oh, as the the server round-trips problem -- programmers are smart, they'll work out how to deal with that imo, just keep crap out of the way and let em have at it.


    Andy :)

    3Carl Tyler  08/19/2007 8:59:39 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    Bob, I don't know if you know but Sametime 7.5.x has a restful interface now for:

    Creating meetings

    changing meetings

    looking up meetings

    deleting meetings

    Only issue I have found with it, is that it's returning a content type of text not xml so it screws up the http xml contents

    4tony palmer  08/19/2007 11:12:20 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)


    of course you could use the apache commons HTTP Client and access using LS2J. :-)


    1) I could be wrong, but is one of the pro's for SOAP that you get an exception object returned vs parsing the XML for an error tag in REST ?

    2) Yes

    3) Depends on the solution really, it's nice to be able to choose the right tool for the right job though.

    4) Don't know. At the very least use plain XML and built in parsers.

    5Dan Sickles  08/20/2007 12:30:28 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    1) Ask Sam. I would make Joe and Sam's book required reading of any developer who touches the web. I also highly recommend Tim Ewald's last 4 posts starting with this:

    { Link }

    2 & 3) Yes. Absolutely.

    4) Case by case, either soap or roll my own restful interface.

    6Michel Van der Meiren  08/20/2007 2:03:22 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    REST! Absolutely. SOAP relies on very complex XML structures and automatic serialization, which makes it virtually impossible to make things performant - ask the WebSphere developers. Another advantage of REST is: you can make your own, which will always be much faster.

    7Nathan T. Freeman  08/20/2007 6:59:03 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    @4 - Having under taken that before, I find it an inadequate solution. For reasons I probably don't even need to share with you, right? :-)

    8Kerr  08/20/2007 7:03:36 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    1) I think there is a lot of SOAP out there using doc literal style, especially where there are interoperability issues. In those cases the envelope content is just a lump of XML you end up parsing yourself anyway.

    Your implication that RESTful web services are necessarily more chatty seems a bit off. In the wild, that may well be the wild case, I don't know, but I don't think there is any reason why it would need to be.

    As for the exception case mentioned above, often only code level exceptions are handled this way with other errors being passed back in a proper reply. This helps separate expected situations from transport and SOAP faults.

    2)You do already don't you? Unless I'm missing something about REST, a whole bunch of the domino URL commands are exactly that. It might need tidied up a bit, refactored and expanded, but it's basicaly there isn't it? I think the question is really what do you need, to expand upon what we already have.


    4)Depends on what I need. Lots of ways to roll your own, including using the SOAP services if required.

    What I'd be keen to see are plenty of places where I can use lower level functionality if I don't want to go with the end solution that Domino gives me out of the box. E.g. if you're doing a view component, don't build the output from a service assuming that the only client is what comes bundled when I select 'use web 2.0 view component'. Keep those interfaces open, and supported.

    From the performance angle of rolling your own, especially with chatty situations, I hope we will have some good news regarding instantiation of Java agents or some suitable replacement. Currently it can be very painful if you need to do a lot of set up code just to make a simple call.

    9Brian Miller  08/20/2007 9:40:18 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    1. Not entirely. I don't think the "cons" you list for REST are all that bad. Fact is, I have a *much* easier time unpickling XML-serialized objects myself than getting any of the SOAP-ful classes/libraries to work. Keep in mind that I, and a lot of developers out there, can't just put class files or other things on the server - we're stuck with what you can get working embedded in an NSF.

    2. Yes

    3. Yes

    4. Depends on the problem I'm trying to solve.

    Overall, I think that SOAP is going the way of Ebbets Field, and REST is where everything's gravitating to. That's just my opinion, but the other commenters seem to be thinking the same way thus far.

    10Wild Bill  08/20/2007 10:11:01 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    Very cooool.

    Oh. Check out { Link } for "traditional" soap debugging. Saved me a bundle of time...

    ---* Bill

    11Keith Nolen  08/20/2007 10:14:18 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    1. Not entirely. Some SOAP advantages you described are actually toolset advantages, not protocol advantages. That said I have not done a lot of work with SOAP. One reason is that the implementation seemed pretty heavyweight. The other reason is that it just hasn't been required in my work.

    2. Yes, I agree.

    3. Yes, I would use it.

    4. Probably plain XML and built-in parsers, depending on the problem in question.

    I did some exploratory work with Domino (R6) and REST about 4 years ago using Tomcat and the built-in servlet engine. This was before AJAX came around and I was working with server-to-server communication rather than client-server, but I was able to get some good stuff working pretty easily.

    Generally speaking I agree that REST is the way to go, especially in an AJX-like world. I would like to see a robust HTTP implementation in Lotusscript, however.

    12Tom Griffith  08/20/2007 10:29:59 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)


    1. Not messing with REST before but doing lots of web services, I see a potential con with REST being limitations on the charactger length of the url string. I also don't see how binary content can be uploaded to a REST service (POST).

    2. I would much rather see some sort of J2EE-like native Domino servlet implementation rather than going down the REST path. It seems to me that xml-based technologies are six of a kind (web service), half a dozen of another (REST). From the cursory reading here and a little googling, I perceive the main advantage of REST over web services is passing data via url parameters. Servlets provide that ability sans any complicated DOM XML parsing. Binary data is also a big could encode content as base64 and chunk it to a servlet. Are binary data uploads (POST) even possible with REST? I can see the GET.

    3. To be honest, probably not. I think the future lies in passing objects like collections (name/value hashmaps in lieu of url parameters) and binary arrays to servers/services. I think the feasibility of paramter passing to a service will diminish over time as more developers embrace oo i/o.

    4. I would keep on trucking with web services. I was able to get ws consumers working in Domino 7 after realizing that domino implemented it's own version of axis but if the full consumer will be implemented in 8, i'll keep using it. I think the web services implementation is brilliant in Domino. It is true that some web services can crank out a ton of complicated stubs via WSDL2Java, but i'd rather deal with that headache than XML/DOM parsing.

    13Erik Brooks  08/20/2007 10:50:45 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    @1 - Great point.

    I've been gobbling up HTTP via LS by using PocketHTTP (albeit a COM), and it's been great. Simple, lightweight (for a COM), fast, and open-source.

    { Link }

    It's come in really handy for some consumption I've done with a couple of huge companies that have quickly thrown together what they *think* is a SOAP-compliant web service, but really isn't. :(

    I'll take a COM object over LS2J any day of the week.

    1) Yes. SOAP is good for big, complex, set-in-stone jobs (e.g. Fortune 100s that never change specs and need to enforce ultra-high-fidelity validation with their 43,234,194 different vendors). REST might involve a little more work in complex scenarios, but is generally MUCH easier for smaller day-to-day stuff.

    2) Yes.

    3) Yes.

    4) Depends. @8 raises a good point - keeping the interfaces open will help foster more user-grown toolkits, etc., and if we don't/can't use the itegrated Domino versions we can roll our own.

    14Lance Spellman  08/24/2007 5:34:10 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    I've been using quite a few REST based services recently like Flickr, and for the majority of light-moderate weight needs I see developers latching on to it.

    With the AJAX Cross-domain issue, I'd like to see data returns from REST be in JSON to step around the issue. Of course, XML would still be available.

    1) Yes

    2) Yes

    3) Yes

    4) If I can achieve more than a 25% success rate in implementing "in the wild" WSDL files as Web Services in 8, that approach works fine. However, most of the time, I can't get a Web Service consumer in 8 to work from the published WSDL. Haven't had a chance to test as much since Gold release, but Betas were not very successful.

    On that note...someone's gotta allow those things to be setup by pointing at the URL for the WSDL!!! Ridiculous to have to go to the site, download or copy the WSDL content to a local file and then point the library at the file. Just point it to the URL.

    15Bob Balaban  08/25/2007 3:50:21 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    Greetings, Geeks!

    As usual, thanks for all the thoughtful postings, and here are some comments/replies:

    @1 - Yep, Nathan is right (as usual)! I may have more to say about this at Lotusphere (or, I may not...)

    @3 - Carl, this sounds (IMHO) like a bug, have you reported it? Should be an easy fix (but what do I know about ST?)

    @4 - Yes, you're correct, getting Java exceptions thrown with a SOAP interface is one of the advantages. However, you could build that feature into the client side of a RESTful interface pretty easily as well, I would think.

    @5 Thanks for the links, Dan

    @8 - I agree that doc/literal does make inter-op easier, it's the one I usually pick. But I don't find as a result that I need to parse any XML myself, the tools still do a fine job of generating client proxy code (RAD for Java, and now Notes 8 does it for both Java and LotusScript). Regarding your point about existing Domino URLs, the honest answer is, yes, ?ReadViewEntries does do that now, with some nice, new options that were added recently. But they don't (IMHO) offer the full coverage we would want to fully support AJAX and other stuff, we need to do more. Regarding new interfaces -- I claim that if we don't make them open and supported, we shouldn't bother at all. Not sure I understand your point about agents, can you expand/clarify?

    @9 - Understand your point, but don't forget that "what you can get working embedded in an NSF" now includes BOTH SOAP provider AND consumer (in Java and LotusScript)

    @12 - I think the URL length limitation is pretty big, 4K, 8K, something like that. I suppose that might not be enough for some, but it should handle 90% of the needs out there (and if I should be proven wrong on that, well, I will publicly eat my words and do my best to find a solution).

    Regarding J2ee/servlets, we do have something for that now, though it's not nearly as robust as I would want. We have plans to upgrade that, but nothing I can talk about yet. Stay tuned. Regarding your point about passing objects, if JSON were an option for the data stream format, would that make you more likely to use it?

    @14 - Hey Lance, ?ReadViewEntries already has a JSON option, I'm sure you already know about that. I'm pretty sure we would continue to offer that. I'm not sure how JSON solves the XSS security issues, though. Can you expand? (offline is fine too...)

    Regarding your issues with N8 consumer, please forward to me any WSDL files that Notes fails on, I will get it in the right hands. As for usig the standard file browsing dialog to specify the WSDL, I found that rather appalling myself. It turns out, though, that you CAN enter a URL in the "file name" control and it will work (not that there's anything about the UI that would lead you to know that...). I have complained to Mary Beth.

    16Stephan H. Wissel  08/26/2007 10:13:16 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    Yes. REST please!!! Of course the SOAP stuff is already there, so it stays....

    What I would like to see for the REST API:

    - uniform URLs that READ data when you use GET and WRITE when you use POST like ?Document ?Form (for new stuff) ?View (yes that would be mass-update). In the simplest case it would be DXL, but some magic to use different schema would be very cool (e.g. a schema <-> item mapper using XSLT?).

    I also would like to see some standardized REST services around mail and scheduling (which could be build into the busytime or the mail template or or or).

    :-) stw

    17Tom Griffith  08/27/2007 12:54:27 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    Hi Bob. Thank you again for the opportunity to take part in this discussion.

    "@12 - I think the URL length limitation is pretty big, 4K, 8K, something like that. I suppose that might not be enough for some, but it should handle 90% of the needs out there (and if I should be proven wrong on that, well, I will publicly eat my words and do my best to find a solution)."

    Yeah, I've somehow managed to have long url parameter strings truncate on me using jsp and servlets. For jsp, I remember I had to implement a submit/redirection workaround in order to preserve the robust data in memory. For servlets, I converted the data to headers.

    However, I agree, your percentage (90%) is accurate, if not more. I just wanted to point it out here because when i ran into truncations, I was trying to mirror notes data in a j2ee environment. I wanted to use the notes unid as a rdbms constraint and the 32 character alphanumeric string does hog up a lot of url space when combined with other parameters and the base url. Some ebay urls get very long with it's unique auction identifier but there doesn't seem to be a problem there. Granted, I was really laying on the parameters but I just wanted to point it out in light of the notes unid.

    "@12 - Regarding J2ee/servlets, we do have something for that now, though it's not nearly as robust as I would want. We have plans to upgrade that, but nothing I can talk about yet. Stay tuned. Regarding your point about passing objects, if JSON were an option for the data stream format, would that make you more likely to use it?"

    Obviously it's personal preferance, but between keeping up with the robust java/j2ee platform (especially i/o and streams), lotusscript (both legacy and enhancements) and web development (css and core javascript), I probably couldn't devote much more to dedicated javascript based object handling.

    I perceive two branches forming from the lotusscript-based domino developer tree...REST appeals to web developers (the majority), web services to the java I think it's all good. I just think there won't be a lot of tool swapping.

    Thank you very much again for allowing me to comment.

    18Tom Griffith  08/27/2007 1:23:19 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    oh yeah, re: JSON, if you can make that an option, i think it would definitely pay-off. I almost think it's a must to allow web developers to stream content. Thank you again.

    19Peter Herrmann  08/27/2007 11:53:43 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    Sounds great. Worth mentioning:

    1. When we use REST as the protocol to access your NMFR server, the data should be able to be returned as objects in either JSON or XML - please, not just XML. This would be a major mistake.

    2. There is no smallish Kb limit on the amount of data if you use the POST method (while there is with the GET method).

    3. If my client (to your server) was a browser, I'd use REST & JSON. If my client was a program, typically I'd use SOAP and XML.

    20Kerr  08/28/2007 9:09:16 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    @15, From an inter-op stand point I've had very poor luck dealing with anything other than primitive values, so as soon as you start need needing more complex structures, just dealing with an xml doc that describes the structure you are after as the payload of a SOAP message has been the way to go. I'm using RAD 6 atm and have found the generated web-services proxies a pain to deal with. Maybe I'm missing something, but if I am it repeatedly eludes me.

    Regarding my point about agents, at the moment (as I understanding it) each run of an agent uses its own classloader, this means that all classes supplied by the agent must be loaded every time the agent is run and all instances of those classes initialised. This includes any classes in libraries. You can alleviate this somewhat by putting some code in the java/ext dir on the server, but this can be a pain to get deployed (admin politics) and can cause conflicts with other databases. Basically there are situations when you would like code in an agent to get initialised once in the context of a database and then stay in memory. I'm trying to avoid saying 'Servlets', because that opens up a huge can of worms ;)

    I've also been reading up a little more on REST principles, so it'll be interesting to see how good a job you do of this. It seems that there is a slightly fanatical wing of the REST camp that gets very upset when REST is not done right. Going back to your original post, I'm not sure exactly what ideas you are toying with. As far as I can tell there are a couple of primary areas. A RESTful api to Domino, which I touched on before, and tooling to enable developers to create RESTful web services to their own apps.

    Reviewing my previous post, I think it may be a little more complicated to get a truly RESTful api for Domino than I had previously assumed. The url length limit is an interesting point here. Obviously this is a question that the REST community must have dealt with before, it's certainly not a problem limited to the Domino world. Traditionally we would just sling the contents in a POST, if need be, and be done with it. That's not going to wash with the REST crowd, POST != GET with bigger input. If it's done properly then the query string commands are going to have to be modified in favour of the correct http request methods.

    As for what facilities you can offer the developer to enable them to provide their own RESTful web services, I would keep it basic, don't try and do too much for now. Give access to the http method and provide good xml and json apis and then get out of the way. If you want to provide more tooling, make it optional.

    21Dan Sickles  08/28/2007 12:16:25 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    @12 @20 url length is a non-issue. REST uses POST and PUT as well as GET and DELETE. REST is not putting commands in the url. GET just gets a resource and PUT and POST create and update resources. DELETE deletes them. That's all. For a good example, updated with the new JSON format, see the couchdb document API:

    { Link }

    That's REST. That's what I want for Domino.

    22Kerr  08/28/2007 1:00:17 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    @21, as I say, I'm still looking at this REST stuff, so there are some subtleties I'm missing. As you say, GET is for getting an existing resource, with you there. Now, I've seen plenty of examples of REST where a GET request contains some form of parameters for a search. It's idempotent and is not modifying anything. What is the semantic there? The URI is a service? I'm making requests of the service, not just retrieving a resource stored at that URI.

    I can easily think of web services that would fit the semantics of GET but could require a larger query string. From the original post, the issue of REST being chatty came up. To avoid egregious chat I would try and bundle several simple requests into one. But doing that could easily blow out a URL. If I POST the request what is the semantic? I'm just trying to get existing data, not create or modify anything. Should I just resign myself to the chat? I suspect that there is some reason why this can be thought of as a valid PUT, but it escapes me for the time being.

    More reading required.

    23Dan Sickles  08/28/2007 3:48:35 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    @22 yeah, the url will have parameters for search, filtering etc. which will be idempotent. I should have said that url length is no more of an issue than a typical idempotent domino url. The domino creatDocument, saveDocument and deleteDocument url commands are not RESTful and would map to PUT, POST and DELETE respectively. I found that once you start thinking in terms of resource uris, the (ahem) rest falls into place.

    24Tom Griffith  08/28/2007 3:55:06 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    @21..Dan, thanks for the link. That is the best documentation I've read so far because it encapsulates the operations. So it appears what would/could normally be url parameters, particularly on GETs, are actually map pairs encapsulated within JSON objects. I really like what I see with it. I do worry about large binary content transfers and how lightweight this protocol is. I suspect content can be base64 encoded as with xml...I'm going to mes around with that or whatever in my spare time. I think @19 #3 sums it up well. Thank you again for the link.

    25Kerr  08/29/2007 4:31:23 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    @24, Tom, maybe I'm not reading you correctly, but you can't pass parameters in a GET in any other way than as query string parameters in the URL. You can't use JSON in the GET request. You could obviously PUT and POST JSON though.

    26Tom Griffith  08/29/2007 2:08:07 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    hi @25 Kerr..out of what I've seen, JSON adds standard request headers like Content-Length, Content-Type to the requests and responses. Obviously i have to look further into JSON, but wouldn't any api that rides on standard http connections have accessibility to the request and response objects? If so, it might be possible to piggyback your own headers to any JSON request (GET, POST, PUT, etc) and avoid parameters all together. If JSON doesn't allow header processing, then like i was thinking earlier, the shelf-life for it, based soley on url parameters, will probably diminish in my opinion or whatever.

    27Kerr  08/29/2007 4:53:40 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    @26 Tom, JSON as such says nothing about http headers, url parameters or anything like that, any more than XML does. It's just way of describing some structured data that happens to be a subset of javascript. How you package that up to squirt down a wire is another thing entirely. Content-Length and Content-Type are just standard HTTP headers.

    28Lance Spellman  09/03/2007 12:07:09 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    @15, The JSON comment was to say that any "new" functionality (like a REST API) would not just return the data in XML, but JSON as well. Yes, the current ReadViewEntries returns JSON (yea!) which is largely unuseable much like it's XML representation as node search is highly impractical (boo!).

    No, what I'm saying is to keep on implementing JSON output in whatever API capabilities we get, as was later voiced by Tom and Peter. Thx!

    29Dan Sickles  09/04/2007 9:48:46 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    Kurt Cagle reviews The Book:

    { Link }

    30Bob Balaban  09/04/2007 10:22:26 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    Greetings, Geeks!

    More comments/replies:

    @16 - Yes Stephan, that is exactly the idea (though packaged services may well come later than the basic plumbing...)

    @18 - We do have a JSON option for ?ReadViewEntries today, I would expect that we will expand that to other places

    @19 - Thanks Peter, good observations

    @20 - I haven't had any trouble using the proxies RAD generates, except when the WSDL is generated by a Microsoft platform. They use conventions (e.g., arrays of complex types) which IBM claims are non-standard (and which Microsoft claims are....).

    You are correct about the performance limitation of server agents when invoked via http. We hope to be dealing with that (possibly by offering other alternatives) in the near future.

    @21 - Sorry, Dan. We are likely to need to make use of URL parameters for Domino's RESTful interfaces, at least to some extent. For example, if we were to provide both DXL and JSON output formatting options, it seems to me that a URL parameter is the right way to go to let people specify. My preference is usually to favor utility over purity.

    @23 - Yeah, I'm reallly hoping it will be that obvious....(sometimes you get lucky!)

    31Dan Sickles  09/04/2007 12:37:15 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    Bob, I also am not a REST purist but I tend to lean that way. URL parameters are's when the URL becomes a command language that it moves away from REST and toward RPC. The Amazon example is not considered purely RESTful for that reason (&Operation=). But it is very popular, more so than the soap API, and it works. I would expect a pragmatic approach for Domino.

    32Axel Janssen  09/05/2007 8:56:00 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    Doesn't serialization of collections in SOAP-webservices get a whole lot less verbose, when using document-style?

    (1) I think tlhere is a difference in webservice-impementation as consumer/producer. As WS-consumer it should support anything possible as its the producer which dictates the style of webservice. Oh well and for producer it would be also nice to support both :-)

    Trying to understand WSDL creates headache (at least for me). Good thing with SOAP is the tool support.

    Auto-Generation of an object graph from the xml can be a huge help. That might be also possible with REST, especially if optionally WADL is used.

    I have seen lots of really crazy stuff with pulling business information from xml. Some people underestimate the complexity. Worst thing I had to maintain were xpath statements mixed in the business logic and in part generated by regular expressions. Only to pull some little data out of a xml file. So platform supported deserialization to objects do matter.

    (2) For ajax infrastructure 1 style is enough and that should be REST. And I second JSON. JSON format with REST architecture. I think alphaworks have framework to use SOAP in javaScript, but please don't go that road as its overkill.

    (3) depends on the project, but it sounds un-intrusive (good)

    (4) I used a mixture of jakarta.HTTPClient with SAX Parsing and self-written xml-to-JavaBean framework in Java on consumer side and Domino Agent/SAX Parsing on producer side with LotusScript. Works too.

    33Andrew Price  09/06/2007 2:48:10 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    REST + JSON + Domino = heaven

    34Dan Sickles  09/11/2007 11:04:59 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    REST API for Lotus Connections:

    { Link }

    35Erik Brooks  09/14/2007 6:30:25 PM  FYI on the REST ideas...

    @15 - I just got finished with a PMR/SPR related to this. :-)

    Domino only supports URLs up to 2K in length. The max-URL-length setting in the server document only lets you *decrease* that amount further.

    Honestly that isn't all that large. ~50 UNIDs plus some other basic CGI information and you're easily there.

    36Bob Balaban  09/16/2007 5:03:18 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    @35 - I'm looking into this. Can you email me the SPR number? 2k does seem rather low...

    37Erik Brooks  09/16/2007 1:20:14 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    No problem Bob. I couldn't find your e-mail very easily, so I'll guess at the standard us/ibm/c-o-m one, and CC your Looseleaf one as well. Let me know here if I screwed things up.

    38Kerr  09/17/2007 10:48:54 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    Apparently IE only supports ~2k in a URL anyway, so relying on the user agent being able to deal with >2k urls is probably not going to work for a large number of users.

    { Link }

    39Bob Balaban  09/17/2007 5:06:11 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    Still more comments (amazing how much great feedback we're getting out of some of these threads!)

    @37 - Checked into that spr, apparently (not sure why) there are a couple of different places in the Domino server where limits are imposed. One is configurable in the server record, the other is not, but is bigger than 2K. I am proposing to the Web Server team that they make the configurable limit apply everywhere.

    @38 - Well, that's unfortunate, but a really good point. Of course, they could change that anytime (is it still 2k in IE7?). Still, 2K for a URL is pretty big. Even if you had a URL with a couple of UNIDs in it and 3-5 &-type options, and a bunch of special-character substitutions (e.g., %20 for <space>, you wouldn't get near 2k.

    We will definitely take URL length into consideration as we design the REST stuff.

    BTW, I just read in the author notes of the "RESTful Web Services" book I mentioned I'm reading that Sam Ruby is an IBM employee. Go figure! I don't know why I didn't know that, as he's such a rock star, but I didn't. Now maybe I can feel ok about emailing him with questions :-)

    40Erik Brooks  09/18/2007 7:53:39 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    @39 - I hadn't checked during my SPR, but the technote referenced @38 states that the limit applies to IE7. Bummer. That's still plenty of good use for some REST stuff, though!

    Wow - Sam Ruby works at IBM? Small world, huh? (Or maybe it's just that IBM employs a fair percentage of the world) :-)

    41Tom Griffith  09/18/2007 12:36:36 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    Bob, this may be off topic a little but I have a really quick question regarding Domino 8...will SOAP with Attachments (SAAJ or SAX-RPC) be supported? Thank you.

    42  09/18/2007 11:51:28 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    @39 my comment @5 "Ask Sam" assumed that you new he was with IBM. I hope he's willing to help....he's helping Damien with couchdb:

    { Link }

    43Edith Birrer  10/10/2007 2:26:22 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    1) Analysis sounds reasonable - and I agree with @5 in a way that every developer should have a reasonable understanding about either way (SOAP and REST) to be able to choose the right one for his/her current project.

    2) Yes, please also REST - it's always good to have a choice.

    3) I have already done webservices in SOAP style, so I'm not afraid about generated code and serialization etc.. But I can imagine plenty of usages for RESTful webservices. So it really depends on the project what I would choose - given that I have a choice!

    4) If I remember correctly, we have already done "webservices" without SOAP and without integrated REST: done HTTP calls and dealt with the result all from scratch (in Java, and programmed in Eclipse, of course). Would be nice to have built-in support though.

    44Marland Kennedy  07/02/2008 3:47:22 PM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    Can I access wsdl file from a web site site using a java agent?

    45  03/12/2010 2:53:25 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    Hallo Bob, is soap with attachments supported by domino webservice provider? I can´t find a way to do it. Thanks in advance.

    46Bob Balaban  03/13/2010 3:10:50 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    Unfortunately, I'm pretty sure Domino does not support attachments on SOAP invocations. In fact, I'm not even sure that the SOAP spec itlself supports that.

    You could try writing a service function that returns an array of byte (byte []), but I don't know if it will work, especially for large files.

    If you find a solution, please let us know!

    47  03/15/2010 4:05:58 AM  Domino Web Services: What if..... SOAP? or REST? (or both?)

    @46: hi bob, thanks for the answer. You are right. I used a byte array as argument for my service function. Now i can send an attachment to the webservise. I did neither try this with large files nor to return a byte array yet. Thanks a lot