Technical Information

Transcription

1 Technical Information Linkon Web Services Version Date Author Magnus Kling Filename Technical Information About Linkon Web Services.doc

2 Table of contents 0 Revisions Technical Information About Linkon Web Services Host Environment Addresses Namespace policy Communication Protocol Identification Example Header Reference Encoding

3 0 Revisions Date Version Section Author Comment Magnus Kling First draft Per Lindberger Proposed changes Magnus Kling Accepted changes. Added section about namespace Magnus Kling Added example of SOAP-header Per Lindberger Updated section on identification. 3

4 1 Technical Information About Linkon Web Services 1.1 Host Environment Addresses The URLs used to access Linkon s web services in production usually are of the form For example, or It may also happen that the URL carries a version indicator at the end as in An automatically generated, reversely engineered WSDL file for each WebService may be found at a similar address by just adding '?wsdl' For example, However, it may be better to study and download the original WSDL contracts through the site The table below indicates where the Linkon web services can be reached in different environments. The environment for system- and integration test (R) is usually the one to use for development activities outside Linkon. Host environment Internal system- and integration test External system- and integration test Acceptance test Test (production-like environment) Production URL Namespace policy The namespaces use two version numbers, a major and a minor number. The major number is increased for larger upgrades. The minor number is increased for smaller changes to an interface. This is used to distinguish between incompatible versions of the interfaces. A client upgrading between versions of a web service with different namespaces will at least have to adapt to use the upgraded interface s namespace. The client will obviously also have to implement any other changes in the API that are not backwards compatible. 1.3 Communication Protocol The communication protocol supported by Linkon s web services is SOAP over HTTP with the addition of SSL. All external communication shall thus be performed over HTTPS. 4

5 1.4 Identification For user authentication a subset of WS-Security is used..a Security/UsernameToken must therefore be supplied in a SOAP header with each request. Along with the UsernameToken another SOAP-header, ClientInformation, must also be supplied. The ClientInformation header typically contains a SalesUnitKey for the requestor and preferences for language (LanguageCode) and perhaps other meta data Example Header Normally tooling on the client side will be responsible for producing the actual XML that makes up the SOAP headers. The end result should look something close to this: <soapenv:header> <wsse:security env:mustunderstand='1' xmlns:wsse=' xmlns:wsu=' 1.0.xsd'> <wsse:usernametoken> <wsse:username>userid</wsse:username> <wsse:password>xxyyzz</wsse:password> </wsse:usernametoken> </wsse:security> <ns2:clientinformation xmlns:ns2=' <ns2:salesunitkey>salesunitkey</ns2:salesunitkey> </ns2:clientinformation> </soapenv:header> Reference For more information regarding WS-Security and UsernameToken, see and Encoding The Linkon web services accept the UTF-8 character encoding as reflected by the XML declaration below: <?xml version="1.0" encoding="utf-8"?> 5