SOA s Service Naming Conventions
1 Contents 1 Purpose... 1 2 Scope... 1 3 General Naming s... 2 3.1 Items Requiring Consistent Naming... 2 3.2 Name Uniqueness... 3 3.3 Name Descriptiveness... 3 3.4 Implementation Agnostic Names... 4 4 Business Service Naming s... 5 4.1 No Service in Name... 5 4.2 Service Name Context... 6 4.3 Data Service Layer Service Name... 6 4.4 Infrastructure Service Layer Service Name... 6 4.5 Business Logic Service Layer Service Name... 7 4.6 Portal Service Name... 7 5 Capability Naming s... 8 5.1 Capability Name Context... 8 5.2 Capability Name Verbs... 9 6 WSDL/SOAP Naming s... 11 6.1 Unique Namespace... 11 6.2 WSDL Namespace Pattern... 11 6.3 WSDL Documentation... 12 6.4 WSDL/XSD File Names... 12 6.5 WSDL Constructs PortType, Port, Binding... 13 6.6 SOAP Action Names... 16 6.7 Service Address Endpoints... 18 7 Service Naming Example - Putting all the Names Together... 20 8 References... 22 ehealth Ontario Confidential ii
Document Location TBD Document Revision History Version Date Author Description 1.1 2012-10-29 E.Neroslavskaya Incorporated feedback from Ron McEwen and Mike Krasnay. 1.1.1 2012-11-01 Sharon MacMillan Formatted and edited. 1.1.2 2012-12-07 E.Neroslavskaya Added Datapower file location policy in 7.4 1.1.3 2013-01-07 E.Neroslavskaya Changed 7.3 WSDL documentation and 7.5 Port naming added versioning 1.2 2013-10-28 E.Neroslavskaya Cosmetic updates Related s Location SOA s - Service Versioning SOA s - Service Taxonomy Terminology Used in this Document This document uses the following terminology: MUST: This word means that the definition is an absolute standard. MUST NOT: This phrase means that the definition is an absolute prohibition. SHOULD: This word means that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course. SHOULD NOT: This phrase means that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label. MAY: This word means that the standard is optional. The service developer may choose to include the item based on the needs of their design. ehealth Ontario Confidential iii
The above definitions are loosely based on the RFC 2119 Key words for use in RFCs to Indicate Requirement Levels as described at: http://www.ietf.org/rfc/rfc2119.txt ehealth Ontario Confidential iv
1 Purpose The purpose of this document is to define the ehealth Ontario standards for architects/developers with respect to naming services and related artifacts. The SOA Principles state that the ized Service Contract design principle is perhaps the most fundamental of the eight service-oriented design principles. It is by means of service contracts that services express their purpose and capabilities (Ref1. SOA Principles Website). In support of a standardized service contract, a number of design patterns are introduced, one of which is the Canonical Expression pattern. The problem that this pattern addresses is that services created by different teams may express similar capabilities in different ways, leading to inconsistencies and potential misunderstandings that further risk denormalization of the service inventory. The stated solution to this problem is to develop naming conventions, and enforce them through a governance process (Ref2. SOA Patterns Website). Nowadays, design time discoverability is becoming more and more important, and service naming is one of the key concepts for defining discoverable services. 2 Scope The scope of the naming standards described in this document includes all ehealth Ontario HIAL exposed services that are described in the SOA Service Catalog. This topic is of particular importance because the structuring of the business names and the challenges involved in maintaining consistency in naming WSDL and XML schema namespaces, services, ports, operations, and other artifacts in the Web Services space have a significant impact on discoverability and the complexity of managing a SOA environment. While the discussion and examples are focused on Web Services (i.e., services defined with a WSDL and SOAP), the basic naming principles apply to other approaches such as XML over JMS, and REST. The standards in this document are intended to be applied to naming services in the service contract. They do not address code-specific naming conventions for specific languages such as Java and C#. Note: Services that have not been designated as members of the HIAL Service Catalog are not required to use the naming standards specified in this document. However, there may be benefit in doing so to promote consistency, as there is the possibility that they may eventually be designated as enterprise services. ehealth Ontario Confidential 1
3 General Naming s 3.1 Items Requiring Consistent Naming Definition Strictness SOA-NM-GN Items requiring consistent naming In a SOA environment there are many things that require names. These include: Abstract Service-related names: Business Service Name; Business Capability Name; Functional Domain and Topic (defined in ehealth Ontario Service Taxonomy). WSDL-related names: The WSDL itself (the name attribute in the top-level <definitions> tag); The WSDL filename; The targetnamespace defined by the WSDL (also in the top-level <definitions> tag). By extension, the target namespace is the logical prefix for the name of each entity defined in the WSDL; The entities defined by the WSDL: services, port types (interface), ports (interface instances); Operations and messages; The soapaction; The schemalocation of each imported XSD file; The endpoint-location attribute for the address element of each service port. Schema-related names: REST names: The XSD filename (if the schema is not embedded in a WSDL); The targetnamespace defined by the Schema (either embedded in the WSDL or a stand-alone XSD). By extension, this namespace is the logical prefix for the name of each entity defined in the schema; The entities defined by the schema: types, elements, and attributes; The schemalocation of each imported XSD file. TBD. WS-Policy names: TBD. Some of these items are actual artifacts such as files. Others are simply logical names for definitions (port types, messages, elements, etc.), or groups of definitions (namespace names). All of them will need to be dealt with by the producers and consumers of services. SHOULD HIAL Registry validation using regular expressions and UGP Gating Review. ehealth Ontario Confidential 2
3.2 Name Uniqueness Definition Strictness Name Uniqueness Services, Capabilities (operations) MUST be distinguishable from other services and operations. This is accomplished by giving a unique name to each service and, within the service, to each port type and operation of that service. Unique names are also required for the WSDLs, messages, data structures, and other artifacts used in the definition of the service. MUST HIAL Registry validation. Best Practice: Eliminate the potential for name collisions across business domains by the addition of domain-specific words where necessary. For example, a one-word service called Protocol can have very different meanings in different domains (e.g., Clinical Research vs. Life Sciences). For example, in clinical research, a more appropriate name would be Study Protocol, whereas, for life sciences there may be many types of protocols, e.g., Laboratory Protocol. 3.3 Name Descriptiveness Definition Name Descriptiveness Service, Capability (operation) names MUST be auto-descriptive and provide the consumer with enough information regarding the behaviour of the service. For conceptual-level specifications, all names MUST be in plain English (e.g., Send Laboratory Order Request), and CamelCase MUST NOT be used. For Logical- and Physical-level specifications, all names MUST use CamelCase (e.g., SendLaboratoryOrderRequest). Rationale: Service names are often used by tooling to generate associated artifacts, e.g., JMS queues or endpoint URIs, or on platforms where spaces or special characters are not permitted. HL7V3: For HL7 transactions, the description field should be used for service operation names. (Refer to the Architecture Decisions document). Strictness MUST UGP review ehealth Ontario Confidential 3
Name Descriptiveness Best Practice: Avoid using acronyms and abbreviations unless they are universally understood across the enterprise. Best Practice: Don t include a version in the service name. 3.4 Implementation Agnostic Names Definition Strictness Implementation Agnostic Names Service, Capability and operation names MUST NOT reveal implementation details. This not only has the potential to lead to confusion if you decide to change the implementation of the service, but is also a security risk as it gives the service consumer insight into how the service may be implemented, which they may be able to exploit. Don t include protocol information in the service names. This is generally unnecessary as the service advertises itself at a particular endpoint which clearly defines the protocol to be used. MUST NOT UGP Review ehealth Ontario Confidential 4
4 Business Service Naming s To facilitate the discovery of services, it is helpful to categorize service names according to a set of preexisting business domains or subject area. Services may exist at different levels, and provide different granularity. A general classification of different levels of services is as follows: Infrastructure service layer (utility-centric) is found in application services involving operations that encapsulate common functions, such as event logging, exception handling, or notification. These reusable services need to be labeled according to a specific processing context, agnostic in terms of any particular solution environment. For example, a utility service might be named Notify. Data service layer (entity-centric) represents a specific-business entity, such as a customer. The labeling of entity-centric business services is often predetermined by the entity name. For example, a service may simply be named Lab Report. Business logic service layer, process or transaction (task-centric) encapsulates process logic. In this case, the thread that ties together the grouped operations is a specific activity being automated by the service logic. Therefore, the use of verbs in service names is common. For example, a task-centric service may be called Get Lab Report, if that accurately represents the task's scope. For additional details, refer to the document entitled SOA Policy Service Taxonomy, Layers (SOAPolicy_ServiceTaxonomy.doc). 4.1 No Service in Name Definition Strictness No Service in Name The name assigned to a Business service SHOULD NOT include the word service. Exceptions to this standard are services that have as their functional context the management of some aspect of service metadata, or the management and coordination of other services. For example, a service that has eligibility for a study as its focal entity should be called Eligibility and not EligibilityService. SHOULD NOT HIAL Registry validation These business service names will be registered in the HIAL SOA Service Registry. ehealth Ontario Confidential 5
4.2 Service Name Context Definition Strictness Service Name context Service names should place the service capabilities/operations in the appropriate context, and define the service scope wisely. Service names should be assigned differently, depending on service type SHOULD UGP gating review Some examples of bad service names are service names which: Lack scope or context. For example: Service Name Inventory what is the scope of "Inventory"? Just managing inventory levels? Or inventory locations? Both? Something else? Have ambiguous naming. For example: OrderManagement::execute What is it that the order management service is actually executing? Is it executing order fulfillment or ordering? 4.3 Data Service Layer Service Name Definition Strictness Data Service Layer (Entity) Service Name For an Entity service, the name assigned SHOULD be the noun that best describes the entity (singular) that is the focal point of the service. <noun> For example, a service that provides agnostic business logic in support of the business entity Person should be called Person. Other examples: LabReport, Invoice. SHOULD UGP gating review 4.4 Infrastructure Service Layer Service Name Definition Infrastructure Service Layer (Utility) Service Name For a Utility service, the name assigned SHOULD best describe the agnostic cross-cutting function that is the context of the service. The minimum combination of verbs and nouns that most closely and adequately describes the cross-cutting function should be used. For example, a service that provides a set of capabilities to log, query, and analyze events and messages across the enterprise, and thus facilitates the auditing of access to sensitive data, should be named Audit Management. Other examples include Logging and Authentication. ehealth Ontario Confidential 6
Strictness Infrastructure Service Layer (Utility) Service Name SHOULD UGP Review 4.5 Business Logic Service Layer Service Name Definition Strictness Business Logic Service (Task) Layer Service Name For a Task (or Orchestrated Task) service, the name assigned SHOULD be either the verb-noun combination, or the noun that best describes the non-agnostic (i.e., contextspecific, single-purpose) business task that is the context of the service. <verb> <noun> For example, a service that provides business process-centric logic for registering a subject to a trial could be called either Register Subject, or Subject Registration. Other examples include Order Management and Medication Management. SHOULD UGP Review 4.6 Portal Service Name Definition Strictness Portal Service Name For Portal services, (portlet) names assigned SHOULD be either the verb-noun or the noun that best describes the non-agnostic business task that is the context of the service, similar to Task Services. [<verb>] <noun> Portlet For example: Lab Results Portlet. SHOULD UGP Review ehealth Ontario Confidential 7
5 Capability Naming s Definition Capability Name pattern All capability names SHOULD follow verb + noun + [ subject ] format, where: verb is the action that the consumer is performing; and noun is the name of the primary object on which the action is being performed. The (optional) subject allows for distinguishing between different logical subjects that may be meaningful to use for certain nouns. Examples include UpdateOrder and UpdateOrderHeader. For standard verb list please refer to SOA-NM-CN Capability Name Verbs Strictness SHOULD UGP Review 5.1 Capability Name Context Definition Strictness Capability Name context The names assigned to the capabilities of a service SHOULD fall within the context of the service that is indicated by the service name. For example, given an entity service called Person, which stores different kinds of Persons including physicians, the view history capability which will provide this functionality should NOT be named QueryPhysicianHistory. It should be named within the context of the service, (i.e., QueryHistory ), as the service may store other kinds of Persons. SHOULD UGP Review Typically, the service name implies the context for the capability, making it useless to repeat the service name in the capability name. For example: OrderManagement::updateOrderShippingAddress would result in the OrderManagement::updateShippingAddress name. ehealth Ontario Confidential 8
5.2 Capability Name Verbs Definition Capability Name verbs All capability names SHOULD use the following standard prefixes for common functionality. According to the Blueprint, standard verbs for HIAL capabilities SHOULD be: Prefix Put Get List Description For operations that create an object completely For operations which retrieve a particular instance of an object using the identifier provided For operations that perform a query and return all the matching objects based on the input criteria If a service exposes functionality that does not correspond with any of the prefixes below, then the most appropriate verb should be chosen. Alternative Prefix Create Add Initiate Update Amend Deactivate Activate Delete/Remove Query/Find Retrieve Publish Submit Withdraw update<objectname> State Description For operations that create an object completely. For operations that add a child object to a parent object. For operations that initiate the creation of an object. For operations that update object attributes. For operations that modify object attributes once an object has been approved, finalized, or submitted. For operations that (soft) delete a particular object. Soft delete does not remove the object from the database, but removes it from the working set. For operations that change the state of an object from deactivated to active. For operations that completely delete a particular object so that it will no longer be retrievable in any context. For operations that perform a query and return all the matching objects based on the input criteria. For operations which retrieve a particular instance of an object using the identifier provided. For operations that publish a particular object or artifact. For operations that submit a particular object for review or approval. For operations that withdraw submission of a particular object for review or approval For operations that change the state of the primary object only. Strictness SHOULD ehealth Ontario Confidential 9
Capability Name verbs UGP Review TBD: REST Service Capabilities follow HTTP operations convention. ehealth Ontario Confidential 10
6 WSDL/SOAP Naming s Web service providers communicate with their customers (consumers) by means of publishing the WSDL of the service. In most cases, developers create the client code for the service by generating classes from the published WSDL file. Therefore, we need to ensure that the WSDL that we publish, and which acts as a bridge, will help service consumers generate good clientside code. 6.1 Unique Namespace Definition Strictness Unique namespace Each service WSDL MUST have its own namespace, to avoid naming conflicts between the messages, ports, and operations of different services. HL7V3: MUST conform to fixed target namespace urn:hl7-org:v3 MUST HIAL Registry Validation Related SOA-NM-GN-02 Name Uniqueness 6.2 WSDL Namespace Pattern Definition WSDL Namespace pattern The idealized structure for a WSDL or XSD namespace name has the form: WSDL: http://ehealthontario.ca/ws/<domain>/[servicename]/v<major> XSD types: http://ehealthontario.ca/xmlns/<domain> Common (cross LOB) XSD types http://ehealthontario.ca/xmlns/<concepttype> Where: domain = functional context or LOB servicename = name of the service major = two digit major version of the service concepttype = element type like Address, Person HL7V3: MUST conform to fixed target namespace urn:hl7-org:v3 ehealth Ontario Confidential 11
Strictness Related WSDL Namespace pattern MUST HIAL Registry validation Examples: http://ehealthontario.ca/ws/hial/audit/v01 http://ehealthontario.ca/ws/olis/reportmanagement/v02 http://ehealthontario.ca/xmlns/client/common Note: Frameworks generate package names from the namespace in Java and.net. <wsdl:definitions name="listpatients" targetnamespace="http://ehealthontario.ca/ws/clentregistry/listpatients/v02 "> </wsdl:definitions> SOA-NM-GN-0x Name Uniqueness 6.3 WSDL Documentation Definition Strictness WSDL Documentation Each service WSDL MUST include documentation with Business name and version of the service. <wsdl:definitions name="listpatients" targetnamespace="http://ehealthontario.ca/ws/clentregistry/listpatients/v02 "> <wsdl:documentation>list Patients,@version V2.0,@date 2011-08 </wsdl:documentation> </wsdl:definitions> MUST HIAL Registry Validation 6.4 WSDL/XSD File Names Definition WSDL/XSD file names Filenames MUST use the structure of the WSDL or XSD namespace as the basis for defining the structure of the filename. The idea is to make the fully qualified filename a URL (or at least a URI). Making it a URL tells you where to locate the file. In order to support multiple service consumers (using different minor versions), it will be necessary to provide access to each schema version and all its dependent parts. ehealth Ontario Confidential 12
WSDL/XSD file names With this approach, the idealized structure for the filename is: http://ehealthontario.ca/ws/<domain>/[servicename]/v<major>.<minor>/<filename> or in the case of a file system: file://ca/ehealthontario/ws/<domain>/<servicename>/v<major>.<minor>/<filename> for Datapower artifacts: local://<domain>/<servicename>/v<major>.<minor>/<schemas>/<filename> Strictness MUST HIAL Registry Validation <wsdl:types> <xsd:schema targetnamespace="http://ehealthontario.ca/clientregistry/managepatient/v02" > <xsd:include schemalocation="ca/ehealthontario/ws/ ClientRegistry/CustomerService/V02.01/CustomerService.xsd"/> </xsd:schema> </wsdl:types> Datapower WSDL: local://olis/getlabresults/v01.01/schemas/reportlabresults.wsdl Related SOA-NM-WS-02 WSDL Namespace pattern 6.5 WSDL Constructs PortType, Port, Binding Definition WSDL Constructs PortType, Port, Binding A port type is a named set of abstract operations and the abstract messages involved. Each porttype name must be unique across all of the services in the namespace. Since the service names also have to be unique in the namespace, incorporating the service name into the porttype name also guarantees the uniqueness of the porttype name. Binding provides details of the porttype s implementation; the binding is then used in defining a port (an actual interface instance) on the service. The port has its own name. WSDL Artifact message porttype SOAP 1.1 binding SOAP 1.2 binding Naming Conventions <operationname>request Response <servicename>service <servicename>soap11binding <servicename>soap12binding ehealth Ontario Confidential 13
WSDL Constructs PortType, Port, Binding SOAP 1.1 port SOAP 1.2 port Service Name <servicename>soap11port_<vmajor> <servicename>soap12port_<vmajor> <servicename>ports HL7V3: MUST conform to rules defined in TLI specification. Strictness MUST HIAL Registry Validation Best practice: Make sure that the WSDL that we publish, and which acts as a bridge, will help service consumers generate good client-side code. wsdl:porttype translates to the Java or C# interface (business interface) of a Web Service (where each operation maps to a method of the interface). Used by C# to create a client class name. wsdl:service in Java translates to, essentially, a factory class that extends javax.xml.ws.service. This class has "get" methods for each port defined as part of the service element. "getportname" methods return a dynamic proxy that implements the service business interface. <wsdl:porttype name="labreportservice"> Business interface <wsdl:operation name="putorder"> <wsdl:input wsa:action="http://ehealthontario.ca/laboratory/labreport/putorder/v01" LabReportServiceClient.cs message="tns:putorderrequest"/> LabReportsService </wsdl:operation> </wsdl:porttype> LabReportService.java <wsdl:binding name="labreportservicesoap11binding" type="tns:labreportservice"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="putorder"> <soap:operation soapaction="http://ehealthontario.ca/laboratory/labreport/putorder/v01"/> <wsdl:input> </wsdl:input> </wsdl:binding> <soap:body use="literal"/> </wsdl:operation> <wsdl:service name="labreportserviceports"> <wsdl:port name="labreportservicesoap11port_v01" Factory class LabReportServicePorts Port getter getlabreportservicesoap11port() ehealth Ontario Confidential 14
WSDL Constructs PortType, Port, Binding binding="tns:labreportservicesoap11binding"> <soap:address location="https://wsgateway.pst.ehealthontario.ca/laboratory/labreport/v01"/> </wsdl:port> </wsdl:service> </wsdl:definitions> Sample C# client: [System.ServiceModel.ServiceContractAttribute(Namespace="http://ehealthon tario.ca/ws/laboratory/labreport/v01", ConfigurationName="LabReportService")] public interface LabReportService { [System.ServiceModel.OperationContractAttribute(IsOneWay=true, Action="http://ehealthontario.ca/Laboratory/LabReport/PutOrder/V01")] } [System.ServiceModel.XmlSerializerFormatAttribute()] void PutOrder(PutOrder request); public partial class LabReportServiceClient : System.ServiceModel.ClientBase<LabReportService>, LabReportService { public LabReportServiceClient(string endpointconfigurationname) : { } base(endpointconfigurationname) [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.Edi torbrowsablestate.advanced)] } void LabReportService.PutOrder(PutOrder request) { } base.channel.putorder(request); Sample Java client: ehealth Ontario Confidential 15
WSDL Constructs PortType, Port, Binding public interface LabReportService { @WebMethod(operationName = "PutOrder", action = "http://ehealthontario.ca/laboratory/labreport/putorder/v01") @Oneway public void putorder(submitorder parameter); } @WebServiceClient(name = "LabReportServicePorts", targetnamespace = "http://ehealthontario.ca/ws/laboratory/labreport/v01", public class LabReportServicePorts { extends Service @WebEndpoint(name = "LabReportServiceSOAP11Port_V01") { } public LabReportService getlabreportservicesoap11port_v01() } return super.getport( ); 6.6 SOAP Action Names Definition SOAP Action Names wsa:action attribute for each WSDL input and output message MUST be defined. wsa:action name MUST reflect the fully qualified operation name, including WSDL namespace, service name, and operation name. http://ehealthontario.ca/<domain>/<servicename>/<operation>/v<major> This approach provides the maximum flexibility in defining endpoints. With this approach, all requests could be sent to a single endpoint (location) without ambiguity: the SOAP action uniquely identifies the required operation. HL7v3: TLI Rule 50 (Ref9 : TLI Spec)The naming convention of WS Actions is designed to support multiple versions of Web Services and HL7 v3 messages, and is structured as: ehealth Ontario Confidential 16
Strictness SOAP Action Names urn:hl7-org:v3:{interaction ID}.{Interaction version} Where {Interaction version} : LE (Local) or NE (Normative) + YYYYMMDD MUST HIAL Registry Validation Use WS-Addressing wsa:action and not an HTTP-specific soapaction to provide protocol neutrality. <wsdl:porttype name="testresultsporttype"> <wsdl:operation name="getresults"> <wsdl:input wsa:action="http://ehealthontario.ca/laboratory/testresults/getresults/v01 " message="tns:getresultsmessage" name="getmessage"/> <wsdl:output wsa:action="http://ehealthontarioca/laboratory/testresults/getresults- Response/V01" message="tns:getresultsresponsemessage" name="getresponse"/> </wsdl:operation> </wsdl:porttype> HL7v3: <wsdl:porttype name="repc_ar000004ca_i"> <wsdl:operation name="repc_in000012ca_i"> <wsdl:documentation> Requests that a new allergy or intolerance record be recorded against the specified patient. </wsdl:documentation> <wsdl:input message="hl7:repc_in000012ca" wsa:action="urn:hl7-org:v3:repc_in000012ca.le20080203"/> <wsdl:output message="hl7:repc_in000012ca-response" wsa:action="urn:hl7-org:v3:repc_in000012ca- Response.LE20080203"/> </wsdl:operation> </wsdl:porttype> Related ehealth Ontario Confidential 17
6.7 Service Address Endpoints Definition Service Address Endpoints Address location names indicate the actual connection points (physical destinations) to which operation requests are directed. Endpoint names identify the lines of business and services, and may also indicate versions. Endpoint locations standards: External DNS: <prefix>.[<region>].<env>.ehealthontario.ca Internal DNS: <prefix>.[<region>].<env>.ont.gss URI: /<domain>/[subdomain]/<servicename>/[vmajor.minor] Ports: 443 TLS; 4443 Mutual SSL; 80 - HTTP Where: 1. prefix: standard prefix for all services IF-GTWY: wsgateway, IF-BKBN: backbone, Native services * lob names. 2. region: HIAL region that is providing/owns service. cgta cswo cneo (nothing for provincial it s default, not applicable for LOB). 3. env: testing environment prod pst fit. 4. domain: business domain ClientRegistry, Laboratory, Portal. 5. subdomain: optional if further refinement is needed; similar to Topic in HL7V3 Orders, Results, PubSub. 6. servicename: name of the service. 7. major.minor: version of the service (e.g., 02 or 02.02). Rule: If client sends specific service version in URI then IF/HIAL routes to this specific version. If client does not send version or minor version, then the IF/HIAL routes request based on client certification to the most appropriate version. Rule: Service MUST be accessed using same endpoint names from Internet and MPN. Strictness MUST HIAL Registry Validation External (provincial and regional gateway services for external clients and clients accessing though MPN): 1. CR Client Management Service Version 1.0 external endpoint in prod: https://wsgateway.prod.ehealthontario.ca/clientregistry/clientmanagemen t/v01 2. CR PubSub Subscription Management Service Version 1.1 external endpoint in pst: https://wsgateway.pst.ehealthontario.ca/clientregistry/pubsub/subscriptio nmanagement/v01.01 3. Patient Portal WSRP service version 2.0 external endpoint in fit: https://wsgateway.fit.ehealthontario.ca/portal/patient/wsrpbaseservice/v 02 4. CR Client Management service CSWO-owned endpoint in prod: https://wsgateway.cswo.prod.ehealthontario.ca/clientregistry/clientmanag ement ehealth Ontario Confidential 18
Service Address Endpoints Internal (provincial and regional gateway/backbone for internal clients): 1. Lab Results Reports Distribution service version 1.0 internal endpoint in prod: https://wsgateway.prod.ont.gss/laboratory/results/reportdistribution/v01 2. Lab Results Reports Distribution service version 2.2 CSWO-owned internal endpoint in prod: https://wsgateway.cswo.prod.ont.gss/laboratory/results/reportdistributio n/v02.02 3. CR Client Management internal backbone endpoint in prod: http://backbone.prod.ont.gss/clientregistry/clientmanagement 4. CR Client Management version 1.0 CSWO-owned internal backbone endpoint in prod: http://backbone.cswo.prod.ont.gss/clientregistry/clientmanagement/v01 Native (Native/LOB services for internal connections): http://sts.ur.prod.ont.gss/userregistry/sts/v1 http://cr.prod.ont.gss/clientregistry/empi/addclient/v2 Architecture Decisions Versioning of URLs options: 1. Content based routing: include version/ client ID in payload: Pros: Single endpoint for all clients, routing done by ESB, supported by WSRR; Cons: Client has to include fields in the payload or ESB has to add code to use some existing fields as version/client IDs. 2. Context based routing: include Major version in URL: Pros: More descriptive endpoints, No code on ESB to do routing; Cons: Client has to be updated and endpoints should be modified for version changes. Decision: Use hybrid of URI and mediated versioning, as it provides the most flexible approach. ehealth Ontario Confidential 19
7 Service Naming Example - Putting all the Names Together The following is an example of service and artifact names based on the policies defined in this document. The Business Context for this example is the Lab Ordering service: Business Domain: Laboratory Business Service Name: Order Request Business Capability: Put Order Request WSDL File OrderRequest.wsdl <wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:xs="http://www.w3.org/2001/xmlschema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:tns="http://ehealthontario.ca/ws/laboratory/labreport/v01" targetnamespace="http://ehealthontario.ca/ws/laboratory/labreport/v01"> <wsdl:documentation>lab Reports Query, @version 1.0, @date 2012-09</wsdl:documentation> <wsdl:types> <xs:schema targetnamespace="http://ehealthontario.ca/ws/laboratory/labreport/v01" xmlns:xs="http://www.w3.org/2001/xmlschema" xmlns="http://ehealthontario.ca/ws/laboratory" elementformdefault="qualified" attributeformdefault="unqualified"> </wsdl:types>.. </xs:schema> <wsdl:message name="putorderrequest"> <wsdl:part name="parameter" element="tns:submitorder"/> </wsdl:message> <wsdl:porttype name="labreportservice"> <wsdl:operation name="putorder"> <wsdl:input wsa:action="http://ehealthontario.ca/laboratory/labreport/putorder" message="tns:putorderrequest"/> </wsdl:operation> </wsdl:porttype> <wsdl:binding name="labreportservicesoap11binding" type="tns:labreportservice"> ehealth Ontario Confidential 20
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="putorder"> <soap:operation soapaction="http://ehealthontario.ca/laboratory/labreport/putorder"/> <wsdl:input> <soap:body use="literal"/> </wsdl:input> </wsdl:operation> </wsdl:binding> <wsdl:service name="labreportserviceports"> <wsdl:port name="labreportservicesoap11port_v01" binding="tns:labreportservicesoap11binding"> <soap:address location="https://wsgateway.pst.ehealthontario.ca/laboratory/labreport/v01"/> </wsdl:port> </wsdl:service> </wsdl:definitions> ehealth Ontario Confidential 21
8 References ID Reference Location/Description Ref Ref2 SOA Principles Web Site: ized Service Contract SOA Patterns Web Site: Canonical Expression http://www.soaprinciples.com/standardized_service_contract.php http://www.soapatterns.org/canonical_expression.php Ref3 SOA: Principles of Service Design P 39 Ref4 ZapThink: Are services Nouns or Verbs? http://www.zapthink.com/2009/10/14/are-services-nouns-or-verbs/ Ref5 Ref6 Ref7 NCI SAIF Service Inventory Blueprint FHIR: Resource design considerations Understanding generated WCF client code https://wiki.nci.nih.gov/display/saif/6.4+- +Catalog+of+NESI+Precepts https://wiki.nci.nih.gov/display/eawiki/soa+service+taxonomy http://wiki.hl7.org/index.php?title=category:fhir_discussion http://msdn.microsoft.com/en-us/library/ms733881.aspx Ref8 JAX-WS client code naming http://myarch.com/wsdl-naming-conventions Ref9 Transport Layer Interoperability Specification http://wiki.marc-hi.ca/tli/application/rule_50 Ref10 Managing endpoints http://documentation.softwareag.com/webmethods/wmsuites/wmsu ite8-2_sp2/centrasite/8-2-sp2_centrasite/igdeploy/impl_endpoints.htm Ref11 Web Services Enablement for Healthcare HL7 Applications http://msdn.microsoft.com/en-us/library/ms954603.aspx ehealth Ontario Confidential 22