Technical Information Linkon Web Services Version 0.4.1 Date 2009-09-09 Author Magnus Kling Filename Technical Information About Linkon Web Services.doc
Table of contents 0 Revisions... 3 1 Technical Information About Linkon Web Services... 4 1.1 Host Environment Addresses... 4 1.2 Namespace policy... 4 1.3 Communication Protocol... 4 1.4 Identification... 5 1.4.1 Example Header 5 1.4.2 Reference 5 1.5 Encoding... 5 2
0 Revisions Date Version Section Author Comment 2009-08-26 0.1 - Magnus Kling First draft 2009-08-28 0.2 - Per Lindberger Proposed changes 2009-08-28 0.3 - Magnus Kling Accepted changes. Added section about namespace. 2009-09-02 0.4 1.4.1 Magnus Kling Added example of SOAP-header 2009-09-09 0.41 1.4.1 Per Lindberger Updated section on identification. 3
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 https://petra2services.linkon.se/<domain>/<service> For example, https://petra2services.linkon.se/customer/privatecustomerservice or https://petra2services.linkon.se/timetable/timetableservice It may also happen that the URL carries a version indicator at the end as in https://petra2services.linkon.se/timetable/timetableservice/1_2 An automatically generated, reversely engineered WSDL file for each WebService may be found at a similar address by just adding '?wsdl' For example, https://petra2services.linkon.se/extendedcustomer/extendedprivatecustomerservice?wsdl However, it may be better to study and download the original WSDL contracts through the site http://docs.linkon.se 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 https://q.petra2services.linkon.se/<service>/<webservice>[/version] https://r.petra2services.linkon.se/<service>/<webservice>[/version] https://a.petra2services.linkon.se/<service>/<webservice>[/version] https://n.petra2services.linkon.se/<service>/<webservice>[/version] https://petra2services.linkon.se/<service>/<webservice>[/version] 1.2 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
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. 1.4.1 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='http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility- 1.0.xsd'> <wsse:usernametoken> <wsse:username>userid</wsse:username> <wsse:password>xxyyzz</wsse:password> </wsse:usernametoken> </wsse:security> <ns2:clientinformation xmlns:ns2='http://petra.linkon.se/commontypes/data/v1_2'> <ns2:salesunitkey>salesunitkey</ns2:salesunitkey> </ns2:clientinformation> </soapenv:header> 1.4.2 Reference For more information regarding WS-Security and UsernameToken, see http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-soapmessagesecurity.pdf and http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-usernametokenprofile.pdf 1.5 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