Admin2012 buchan web_services-v101


Published on

  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Admin2012 buchan web_services-v101

  1. 1. Who am I?•  Bill Buchan, CEO of hadsl - one of the vendors on theshowfloors  Come visit the booth - we don’t bite•  Dual PCLP in v3, v4, v5, v6, v7, v8, and v8.5•  Enterprise-level consultant on Domino since 1995
  2. 2. What we’ll cover•  Introduction•  Web Services Overview•  Using Domino to provide Soap Based Web Services•  Using Notes to consume Web Services•  Using xPages to provide REST based Web services•  Consuming web services from C#•  Wrap up
  3. 3. Introduction•  I am Bill Buchan. I am:s  A blogger - http://www.billbuchan.coms  A principal of HADSL - http://www.hadsl.coms  A Notes veteran of some 14 years•  You ares  Lotus Domino developerss  Interested in starting or enhancing Web Services in yourenvironments  Familiar with LotusScript, and perhaps xPages/Java
  4. 4. •  Introduction•  Web Services Overview•  Using Domino to provide Soap Based Web Services•  Using Notes to consume Web Services•  Using xPages to provide REST based Web services•  Consuming web services from C#•  Wrap upWhat we’ll cover
  5. 5. A quick overview•  SOAP Stands fors  Simple Object Activation Protocol•  SOAP Based Web services are:s  A standard application to application protocol for exchanging structured data„  Usually (but not always) using the http protocol„  Usually (but not always) using XML„  Usually we provide meta-information on what our service will do, using alanguage called WSDL (Web Service Description Language) – formatted inXML.•  Web services are Language independent, Platform independent, Data formatrepresentation independent•  But hopefully you all knew this already...
  6. 6. Web Services Architecture•  The players:s  The Web Service server„  Can answer questions on what it can do„  Can accept requests from Web Service clients„  Can respond to requests from Web service clientss  The Web Service client (or consumer)‫‏‬„  Knows where the web service server is located„  Knows the services that it requires„  Knows how to prepare a Web Services Query„  Knows how to interpret the returned data
  7. 7. 7 Web Services Protocol§  A typical web service session looks like:  Client to Web Service Server§  “Tell me the answer to this question”  Web Service Server§  “Here it is”§  Conclusion:  The clients drive the conversation  The Server cannot initiate a conversation with the client.
  8. 8. 8 Web Services Protocol (in more detail)‫‏‬§  The Web Services Protocol:  The client decides it needs to ask the server for some informationIt constructs the relevant XML based web services query (eitherdynamically or in a static fashion depending on the complexity of theapplication)‫‏‬  It then connects to the Web Service Server§  Pushing the web request up as an HTTP Post request§  It waits for a response  The Web service server then Posts back an XML payload representing theanswer  The client then unpacks and interprets the data.
  9. 9. 9 This sounds hard...•  Not really.s  Its a combination of web protocol and XML construction andunpackings  Most of the hard work is done for you by the various WebService servers and Consumerss  Its fairly easy to debug using the correct tools
  10. 10. What about REST?•  REST stands for:„  REpresentational State Transfer•  REST Meanss  The query is passed as the URLs  The results can be in XML or RESTs  NO WSDL•  REST iss  Far more lightweights  Easier to parse in JavaScript•  Choose the best approach…10
  11. 11. REST versus Web Services?•  Is REST a Web Service ? Well, not really•  Which is best?s  Web services are good for delivering very structured, complexinformation in nested XSLs  REST is very convenient to parse, and is better for lightweightframeworks such as JavaScript•  Pick your architecture based on your consumer needs, and yourauthentication requirements11
  12. 12. Authentication•  Some web services or REST services can supply informationwithout authentications  But we live in the real world•  Authentication is proving you are allowed to see this data•  Can be achieved by:s  Passing a Session Identifier in a cookies  Passing a username/password pair to an applications  Authenticating using Kerberos/NTLM in an Active Directoryworld•  A simple rule of thumbs  Lightweight consumers tend to use cookiess  Heavyweight data lifting services tend to use authentication12
  13. 13. Authentication Gotchas•  Some frameworks – such as JavaScript or Flex – can re-use thecookie provided on their launch pages  Very convenient for us. Just have the consumer launch the RichInternet Application from that page•  Some more complex applications require KERBEROSauthentications  A C# Windows based service, for instance, might run underspecific service credentials, which can then be Single-Sign-Onauthenticated to Domino„  See SPNEGNO and/or IIS Websphere Plugin•  Otherwises  You will have to hold encrypted username/password keys.13
  14. 14. 14 A sample application•  Fairly simple Domino Contact Databases  A single ‘Contact’ form with some informations  Not meant to be a ‘real-world’ example - Its here to demonstratethe techniques•  All example code is in the databases  Simple to figure out and ‘research’s  Probably is not best practice!
  15. 15. 15 Example Database:
  16. 16. 16 Example Database: Contacts.nsf
  17. 17. 17 How do we test a web service?•  I recommend SoapUIs  Its free!• •  It allows you to interrogate a web services  And build test case with real data
  18. 18. 18 SoapUI: Example Screenshot
  19. 19. •  Introduction•  Web Services Overview•  Using Domino to provide Soap Based Web Services•  Using Notes to consume Web Services•  Using xPages to provide REST based Web services•  Consuming web services from C#•  Wrap upWhat we’ll cover
  20. 20. 20 Domino Web Service Server•  By far the simplest is to use a LotusScript Web Services  The majority of the work is done for you!•  Servlets should be avoided unlesss  You are running on Domino v6.5.x or olders  You absolutely require persistence
  21. 21. 21 LotusScript Web Services•  Introduced in Lotus Domino 7•  Robust•  Code the web service using LotusScript•  Fairly high performance buts  Remember: Lack of persistence between calls, so„  Be aware of what your code is doing!„  Use ‘Agent Profiling’ to see timings…
  22. 22. 22 Profiling a Web Service•  LotusScript web services arevery similar to LotusScript agentss  So you can profile them.s  Enable Profiling on the WebServices Properties tabs  View the last run profile:„  Right click on the Web Service„  View Profile Results
  23. 23. 23 A Sample Profile•  This shows how long the agent took to run, and how long theagent spent inside the Notes Object Interfaces  In our case, 761ms total, and 0ms within NOIs  One call to CurrentDatabase, and one call to Title.s  Obviously, this wasn’t a very interesting web service call…
  24. 24. 24 Designing a Web Service•  Spend time thinking about how your consumer will use this webservice.s  More time thinking, less time codings  You do NOT want to change this web service interface often„  Instead - roll out a new web services  Think through client use casess  Remember - you can use LotusScript to perform complexbusiness rules, and provide summary data to your consumer„  Don’t assume the consumer has lots of CPU or memory§  BlackBerry smartphones / Windows Mobile ?•  Put complex code in script libraries, and call them„  It means you can put a normal agent ‘test harness’ around itand debug it
  25. 25. 25 Contacts.nsf•  In our case we wish to:s  Be able to list all users by Name, by Departments  Be able to get details on a particular users  Be able to search for users•  Do wes  Pass all fields back as web service items?s  Pass back an array of fields?•  In this case, we pass back Web Service Itemss  Assume data mapping knowledge and responsibility.
  26. 26. 26 Web Service Design•  We design our web service interface within a ‘Class’ inLotusScript.s  At this point, you probably wished that you studied theObject Orientated LotusScript sessions I used to give…•  Our web service will expose all ‘public’ methods andpropertiess  We do not have to put all the code in one ‘class’s  Beware of extending existing classes - you might exposemore than you want!„  Beware over-exposure…
  27. 27. 27 Web Service Design•  LotusScript does NOT allow functions to return Arrays.s  This is a language limitation, not a Web Service Limitations  It can return simple types - but not variants (web servicesdoes not support them)s  Instances of other classes…„  Which can contain other classes•  We need to use arrays to return resultss  For instance, we need to return an array of Zero or moreentries to list our users. How do we do that?•  We can define a class and return an instance of that class…
  28. 28. 28 Returning complex types•  We can define a class called‘ReturnArray’ which has a singlearray as a public member.s  The constructor initialises thearray so that it has one blank entry.•  We can then populate this arraywith one or more entries.•  Nd7 supports arrays with oneelement or more - nd8 supports‘empty’ arrays.Class returnArrayPublic S() As StringSub newRedim S(0)S(0) = ""End SubEnd Class
  29. 29. 29 Complex types…•  We shall return our Personcontact record using a class.s  We DON’T have a constructors  All elements are Public - so it’llbe exposed to the Web Serviceas data.s  Our property names will beused by the web service asfield namess  Since LotusScript is caseinsensitive, the web servicefield names will beUPPERCASE.Class PersonPublic FirstName As StringPublic MiddleInitials As StringPublic LastName As StringPublic FullName As StringPublic Telephone As StringPublic Cellphone As StringPublic eMail As StringPublic HomePhone As StringPublic Department as StringPublic Notes As StringEnd Class
  30. 30. 30 Lets make it better•  We need to add:s  Logging. We need to know when it works, and importantly,when it does nots  Error Handling. We need to pass errors back to the consumers  Security. We might want to harden this service somewhat•  We committed the following sins:s  We put all the code in the web service itself, making it hard totest. Best to consider embedding most of the code in scriptlibrariess  We’ve tightly bound the data structures in our data to ourweb service„  If we add more fields to our contact record - we shall haveto change the web service. And therefore, all our clientswill have to be checked and/or recompiled.„  If the data set is likely to change, construct a more flexibledata-mapping schema
  31. 31. 31 ND7 and ND8 differences•  Web services built or compiled in Notes 8 Designer WONT runon ND7 anymore!So be careful about what web services you host on whichservers, and which version of designer you use.s  Just bear this version difference in the same manner as allother version differences.
  32. 32. 32 ND7 and ND8 differences•  In ND7, the class used for the web service has to reside in theweb service design element. In ND8, this can be in a scriptlibrary.s  This means that for complex services, you can place all thebusiness code in a script library, allowing simpleconstruction of a test harness.•  ND8 now supports code in Java Libraries•  ND8 supports more error handling SOAP elements•  ND8 supports ‘empty’ arrays - nd7 does not
  33. 33. •  Introduction•  Web Services Overview•  Using Domino to provide Soap Based Web Services•  Using Notes to consume Web Services•  Using xPages to provide REST based Web services•  Consuming web services from C#•  Wrap upWhat we’ll cover
  34. 34. 34 Consuming a web service•  Why consume web services?s  To gain access to information in other systemss  To prevent the synchronisation and replication of external data sources toNotess  Real time, up to date data lookup•  Where?s  We could use a scheduled Java agent in Domino to interrogate externalservices - no UI means you have to monitor and checks  We could use client-driven code on the client workstation - be aware of networkissues between the clients and the remote service
  35. 35. 35 Overview•  Securitys  Remote web services may require„  Username/password login, Encrypted username/passwordpairs in data, SSL.•  Things changes  You may have to change your web service consumer toaccommodate thiss  The remote web service may moves  When designing, don’t hard-code…
  36. 36. 36 Consuming Web Services•  Summary:s  Notes 8 - Its very simple - It works in LotusScript and in Javas  It does a lot of work for you•  How do I construct a Web Service Consumer in LotusScript?s  Create a new, empty script librarys  Click on the Import WSDL buttons  It creates a Class definitions  You can then “use” the script library and class.
  37. 37. 37 Consuming Web Services•  On the nd8 basic client: create a new LotusScript ScriptLibrary:•  Click on the WSDL button…
  38. 38. Consuming Web Services•  On nd8 standarddesigner, go toCode, Web servicesconsumer
  39. 39. Consuming Web services•  Click on ‘New Web service consumer’ and fill in the dialog:
  40. 40. Consuming web services•  And then use the web service consumer library that has beencreated:
  41. 41. 41 Consuming Web Services•  It needs a WSDL file. Whats that?s  You can open the WSDLdefinition for your webservice in your browsers  Use View Source, and save that asa WSDL file.s  Select it…•  Designer will then constructhelper classes and a mainclass which we can then call•  That’s it!Sub InitializeDim C As New ContactsDim V As VariantSet V = C.listUsers()Forall thisUser In V.SPrint "Found User: " + thisUserEnd ForallEnd Sub
  42. 42. 42 Gotchas•  The entire LotusScript library is taken up with the computedWeb service definition. Best not to make changes.s  Next time its refreshed, you will lose those changes!•  If you change the web service, you must remember to updatethe Web Services consumer.s  It does not take long - so don’t forget it.s  And when you change the web service consumer scriptlibrary, you must recompile all the LotusScript that relies onit.„  ‘Tools, Recompile LotusScript’ is your friend
  43. 43. 43 Gotchas•  It requires the Notes 8 client to run on:s  We as Application Developers deploy solutions on users’target notes clientss  Notes 8 may not yet be adopted in your environment„  So catch up!s  This may help drive the upgrade process•  What if you need Web Service consumption now, and are notyet on Notes 8?s  You can use MS COM objectss  You can hand-code Java-based agents which perform WebService callss  But really. Upgrade
  44. 44. Summary•  Web Servicess  Are pretty straightforwards  An important part of your armourys  Help break down barriers between Domino and other systemss  Help prevent data duplication in your environment•  By now, you know enough to make a real difference•  Keep learning.
  45. 45. •  Introduction•  Web Services Overview•  Using Domino to provide Soap Based Web Services•  Using Notes to consume Web Services•  Using xPages to provide REST based Web services•  Consuming web services from C#•  Wrap upWhat we’ll cover
  46. 46. How difficult is it to provide REST from xPages?•  Its pretty simple•  It relies on the Extension Librarys  (Its pretty straightforward, but we’ll not cover it here)•  What does REST look like?46
  47. 47. So REST can be JSON or XML•  JSON is JavaScript Object Notations  It can be directly parsed in JavaScript (and many otherlanguages)s  You can pass collections of objects (which may contain otherobjects)•  Considerations:s  It can get large. You might want to keep it light:„  So don’t try and pass back thousands of records. Let theconsumer ‘page’ through a reasonable set of resultss  Everything is a String or a Number„  So decide quickly how to pass back currency, dates, etc.•  See for more information47
  48. 48. Lets add a JSON based REST service:•  Add a new xPage. I calledmine RestService.xsp•  Drag in a REST object fromthe Data Access Controlsarea:48
  49. 49. JSON REST Service:•  Give it a name: I called mine ‘all’•  Set ViewName to the name ofyour view. In this case,‘Contacts.FirstName’•  Set service to ‘xe:viewJsonService’•  Set ‘pathInfo’ to the URL youwish to use. I set mine to ‘all’•  Set contentType. I set mine to ‘text/plain’, but ‘application/JSON’ is better•  I set ‘compact’ to ‘false’ so we could read it. Set it to ‘true’•  Now set your columns…49
  50. 50. JSON REST Service•  I set my columns to:•  But of course you could set more orless columns, and compute variableson the fly•  Lastly, I set SystemColumns to the computed value of ‘false’ toskip the system computed columns50
  51. 51. JSON Summary•  You don’t have to use xPages for all the site – you can use xPagesfor the JSON part•  The REST based xPages JSON provider is pretty basic, but veryfasts  Matt White (of ideaJam and xPages101 fame) has measured thisAPI versus traditional web service pages, and found it to be atleast 10x fasters  It might be worth the effort to implement for that sort ofperformance gain51
  52. 52. •  Introduction•  Web Services Overview•  Using Domino to provide Soap Based Web Services•  Using Notes to consume Web Services•  Using xPages to provide REST based Web services•  Consuming web services from C#•  Wrap upWhat we’ll cover
  53. 53. Consuming Web Services from C#•  C# is part of Microsoft’s Visual Studio suite of langagess  Similar to Java in terms of being Object Orientateds  It’s a very useful tool in our corporate landscape•  So lets construct a C# Web Services client for this application:s  It’ll be simple – a console based applications  It’ll just pull data via web servicess  It’ll ignore authentication, error handling, etc.•  But it will demonstrate the technique53
  54. 54. C# Starter•  Create a new project in VS2010s  A console applications  C# Based54
  55. 55. Adding the Service Reference•  Right click on your project (on the right, in the Solution Explorerpane) and select ‘Add Service Reference’55
  56. 56. Pass the WSDL for the service56•  Enter the WSDL URL, and give a name to the web service, thenclick ‘Advanced’
  57. 57. Add a Web Reference•  Now click on ‘Web Reference’57
  58. 58. 58•  Finally, enter the URL again, and update the reference
  59. 59. Now add a splash of code…59EndpointAddress endpoint =new EndpointAddress(new Uri(DominoHostName));BasicHttpBinding httpBinding = new BasicHttpBinding();httpBinding.Security.Mode =BasicHttpSecurityMode.TransportCredentialOnly;httpBinding.Security.Transport.ClientCredentialType =HttpClientCredentialType.Basic;ws = new sr1.ContactsService();ws.Credentials = new NetworkCredential(DominoUserName, DominoPassword);Console.WriteLine("Program name is: " + ws.GETAPPLICATIONNAME());
  60. 60. C# Conclusion•  It’s a highly scalable, secure environment•  This is a trivial example –it can handle millions of records, andvery complex structures•  The LINQ structures within C# make data comparison andreporting very simple•  Step through it with the debugger and all will be revealed.60
  61. 61. What we’ll cover•  Introduction•  Web Services Overview•  Using Domino to provide Soap Based Web Services•  Using Notes to consume Web Services•  Using xPages to provide REST based Web services•  Consuming web services from C#•  Wrap up
  62. 62. Resources•  SOAPUI –•  The xPages Extension Library –•  xPages101 series of xPages tutorials –•  All my previous presentations are on http://www.hadsl.com62
  63. 63. 7 Key Points to Take Home•  Web services are a platform and application agnostic way ofpassing information around•  Both Web Services and REST are lightweight protocols andshould be used for smaller packets of information•  Use SoapUI to help debug SOAP based web services•  Authentication needs to be architected•  Lotus Domino servers can easily serve web services using classicLotusScript and Java•  xPages can provide information via REST•  xPages REST is 10x faster than LotusScript based SOAP webservices63
  64. 64. Your Turn!64How to contact me:Bill