B2b web Service Guidelines V2 rsvz enterprise Architecture
Download 0.95 Mb.
|
- Navigate this page:
- Identification
- Configuraton Management Release Management
- Configuration Items Versions
- From Change Requests (CR) to Releases
- Service Definition Anatomy
Interface DocumentationEach version of a service MUST be accompanied by a document providing at least the following information: Identification Operations Samples The filename of the document should match the following pattern: Example: Affiliation_V3.docx IdentificationThe interface documentation MUST clearly state the name, version and namespace of the service, and the version of the B2B Web Service Guidelines that applies to it. For services provided by NISSE, the location of the WSDL MUST also be included. OperationsThe following information MUST be provided for each operation: Goal Operation type List of error codes Pre –and postconditions Any deviations from the B2B Web Service Guidelines that apply to the service MUST also be clearly documented. SamplesAn example of the message(s) exchanged for each operation SHOULD be included for reference. Note: Technical ACKs sent as part of a POW operation SHOULD NOT be included. Configuraton Management & Release ManagementIntroduction of ConceptsWeb Service DefinitionsWeb Services are essentially service interfaces, things through which an interface user communicates with the interface implementor in a well-defined way and with the expectation that the interface implementor will do as asked – i.e. execute that functionality. Interfaces are not new – (Web) Services is just another technology implementing the same idea but with other – more open – technologies. Service Definitions define what functionality is offered by an interface and how it should be called upon. WSDL’s are the first and most important part of this interface description, these are automatable definitions in the sense that all communication code can be generated from it, either by codegeneration tools or Enterprise Service Buses (ESB). WSDL’s import schema XSD files, which typically define the functional parts of the input and output of the service operations. Finally, a Service Definition also needs a textual description, on how to use the interface – not everything can be described using WSDL or XSD’s. RSVZ-INASTI will be the ‘owner’ of these Service Definitions, although they are defined together with all parties involved. All parties, NISSE and the SIFs, must adhere to it8. These definitions include: WSDL’s (.wsdl files) containing: PortTypes: a set of operations; PortType is also called ‘abstract interface’. Operations, including input and optionally output parameters, as well as faults Structure of the parameters and faults, defined with XML Schema A binding of the PortType to the SOAP protocol and, more importantly, a URL where the service is offerred and can be called XSD Schemas (.xsd files) imported by the WSDL, and used indirectly for input and output parameters. Accompagning documentation: For other transport protocols than http: transport type, ip adresses etc. For http these data are included in the WSDL. Functional information on the operations. Other information, such as authentication and authorisation information, maximum sizes, etc. An implementation of a web service then is a Service. The term Service often is used for both the implementation and its definition – the context makes clear what is meant. A Service Definition contains a number of Operations. The communicating party implementing the operation acts as a Service Provider for this operation, the one using the operation is the Service Consumer. Sometimes Server is used as an alias for Service Provider, and Client or Caller are used as an alias for Service Consumer. A communicating party typically acts at the same time as Service Provider and Consumer for the same Service, for some operations it is the consumer whereas for others it is the provider. Configuration Items & VersionsAll files, including WSDL files, Schema files and accompanying Documentation, are configuration items. A configuration is a set of configuration items that are or should be used together. For example, a WSDL file imports one or more Schema files that it needs and is accompanied by a Word document describing its operations; all these files together form a configuration. Each configuration item has a version. In essence this is just a name or number, used as a label attached to a specific version of a configuration item. Taking into account versions of configuration items, a configuration is a set of configuration items whereby each configuration item has a specific version. In this respect we also speak of a baseline. In practice some text label indicating the baseline, e.g. “build_of_2007-04-01” is attached to each included configuration item version – this label then is the baseline label. Note that tag and label are aliases; both are names or numbers attached to something else. In the example below the configuration baseline labeled “build_of_2007-04-01” consists of configuration item Affiliation.wsdl version 1 and configuration item Base.xsd version 2.
A release is a baseline that has been tested and approved for production. While a baseline is not yet a release, while it is in test, we speak of a release candidate. When tests are successful it becomes a release, if not successful it remains a –failed– release candidate. From Change Requests (CR) to ReleasesChange Requests (CR) are described in a separate document; here we only describe the relationship to configuration management and releases. Once a CR has been approved it is assigned to a future release. It is possible that this will be the next release, on which work is already being done, or in a later release scheduled for perhaps 6 months later. This is a decision of the Change Control Board (CCB). In fact, a Release is a collection of implemented Change Requests, assigned to that Release. It is not feasible to have one Release per CR – this would cause very frequent new releases and associated work from all parties involved. Services are used by many parties ( 10 funds), so any change in a service impacts all of these parties. Therefore each change and release must be carefully coordinated, and with dozens of participating parties this is not an easy task. This coordination is, again, the responsibility of the Change Control Board. Service Definition AnatomyGuidelineA Service Definition MUST be described using WSDL, SHOULD import XML Schemas for messages (i.e. input and output parameters of operations) and MUST have a textual description of non-automatable aspects. A Service Definition MUST be identified by a Name and a Version. A Service Definition MUST consist of: one or more Endpoints an Endpoint is of one of the following possible types: NISSE – contains all operations of which NISSE is the service provider SIF – like NISSE, but for operations of which a SIF is the service provider only one Endpoint Type can appear in a Service Definition ExplanationThis guideline describes the base service structure which we use. The next guidelines build further upon this guideline; Versions are described in a later guideline. We intentionally limit the flexibility WSDL and SOAP offer, to make it easier to understand and use. The figure below summarizes the structure and rules of a Service Definition. 
Note that other guidelines also apply. For example, the allowed types of operations and faults were described earlier. A Service Definition is an umbrella concept, defining a service. As we’ll see later it corresponds to exactly one namespace, and 2 or 3 WSDL files. An Endpoint has a very concrete aspect, at runtime it is a URL at which you can call operations. This corresponds to exactly one . In our Service Definitions there is a one-to-one relationship between PortType, Binding and EndPoint elements in WSDL. The Endpoint types are defined by the communicating partner, NISSE or SIF. Discriminating between “provider” allows us to easily split Operations between provider and consumer, which is handy for generation tools – see also the guideline on files. ExampleTODO. Directory: schemas schemas -> Recommended list of diagrams for the Anatomy final examination Skeleton, joints, muscles schemas -> State of Maine-Sample Automobile Lifts and Hoists Schema-Sample Download 0.95 Mb. Share with your friends:
|