Designing web services for BMC CMDB

This section describes standards, recommendations, and guidelines for creating WSDL interfaces to services stored in the CMDB Web Services Registry so that applications can inter operate more effectively and efficiently. Interoperability is the ability of two or more applications to exchange information and to use the information that they exchanged. To do this, interfaces must 

• be compliant with standards
• be consistent semantically and syntactically
• be extensible in a structured and predictable manner

Required and recommended standards

CMDB Web Services must comply with the following standards.

• XML 1.0
• SOAP 1.1
• WSDL 1.1
• WS-I Basic Profile (BP) 1.1
• UDDI V3.0.2

The WS-I Basic Profile (BP) 1.1 interprets WSDL 1.1 so that it enhances interoperability. BMC uses both WSDL 1.1 and WS-I Basic Profile (BP) 1.1 for developing WSDL interfaces. 

Several versions of WSDL are available, but BMC uses WSDL 1.1 for the following reasons:

• It is the most widely implemented and deployed version.
• TIBCO, which BMC uses in its web services architecture, supports this version.
• WSDL 2.0 has not gained widespread adoption.

Where appropriate, all Web Services definitions should comply with the following WS-Management (WS-MAN) standards.

• WS-Addressing
• WS-Security
• WS-Transfer
• WS-Enumeration
• WS-Eventing
• WS-ReliableMessaging

Where possible, follow these standards in substance and style to develop web services. The BMC SOA implements these standards.

Also, although not part of WS-MAN, WS-ReliableMessaging provides means for sending and receiving SOAP messages reliably.

Durable and well-defined interfaces

You can define how interfaces can handle changes and must be modified. You can use the following methods:

• Durable interfaces — One parameter that is an XML stream and out-of-band XML documentation of the syntax and semantics.
  In this approach, XML documents define the interface semantics and are transferred through these interfaces. To process these XML payloads, out-of-band agreements must be in place to understand their content. The parameter is typically an XML stream, such as xs:Any.
• Well-defined interfaces — A set of well-defined parameters (similar to most programming language APIs)
  WSDL interfaces look like traditional programming APIs where every parameter is explicitly and atomically define. Applications exchange all information with these parameters.
• Hybrid interfaces — A small set of well-defined parameters and one extensibility parameter which is an XML stream.

BMC does not require one particular approach, but you should be aware of the advantages and disadvantages of each. The following table summarizes the advantages and disadvantages of durable and well-defined interfaces.

Summary of durable and well-defined interfaces 

We recommend that you balance durable and well-defined interfaces by providing a small set of well-defined interfaces and one extensible parameter. This extensible parameter could be an xs:any type that passes an XML stream with almost any set of data. In terms of XML, xs:any cannot be validated given the current XML schema. Therefore, it can accommodate types of parameters that might not have been anticipated when the API was initially designed.

For example, you could use an extensible xs:Any parameter to federate data from several data sources. All the data sources use a common data model. For those attributes, you can use a fixed number of well-defined parameters. But each source also presents data that is unique to that model. To exchange this data among sources, you can use the extensible xs:Any parameter to pass an XML string with this unique information.

Syntax for web services

BMC has developed a list of verbs and nouns to create consistency across interfaces. You can use these verbs and nouns in your operations or as guidelines for defining verbs and nouns.

Verbs

As a guideline, create operations with generic verbs, and avoid embedding semantics details in the operation:

• The objects that the operation manipulates
• Constraints that might affect the operation

Using generic verbs allows you to extend verbs more easily for new objects and constraints.

For example, an operation named GetCriticalPriority uses a complex verb that includes the object (critical statuses). A simpler, more generic Get operation could use Priority and Critical as parameters. If the web service could provide status information for low priority, the Get operation could be extended with a Low value for the Priority parameter. With the GetCriticalPriority operation, a new GetLowPriority operation is required.

BMC derived the following verbs from the WS-* Standards listed in Required and recommended standards.

• Get — To retrieve data.
• Put — To send data.
• Delete — To erase data.
• Create — To instantiate data.
• Subscribe — To express interest in a message.
• Unsubscribe — To end a subscription.
• End — To mark the end of a some interaction such a subscription or enumeration.
• Enumerate — To begin an enumeration (batch) of data.
• Pull — To get an enumeration (batch) of data.
• Renew — To renew (such as an enumeration).
• Release — To release resources such as enumerations.
• Submit — To send an object (such as a job) for processing.

Nouns

Like operational verbs, you should use nouns that you can extend.

For example, a Get operation uses a {LowPriority}} parameter that includes a specific priority value. To retrieve other priority values requires a new parameter for each:

Get [LowPriority|MediumPriority|CriticalPriority]

A simpler syntax of Get Priority allows Priority to be extended for different values as needed.

BMC derived the following nouns from operations defined by BMC products. You can use these nouns in your operations or as guidelines for defining nouns.

• Activity — A set of actions designed to achieve a particular result.
• Alert — A warning that a threshold has been reached, something has changed, or a failure has occurred.
• Asset — Any resource or capability. Assets of a service provider include anything that could contribute to the delivery of a service.
• Attribute — A single property of an instance or class or information about a CI.
• Certificate — An object that associates some level of validity or credibility to the holder.
• Change — The addition, modification, or removal of anything that could have an effect on IT services.
• ChangeRequest — A formal proposal for a change.
• Class — A group of things that have a common representation and behavior.
• Configuration Item — Any component that needs to be managed to deliver an IT service.
• Contract — A legally binding agreement between two or more parties.
• ContractLineItem — A representation of some specific terms, conditions or obligations of a Contract.
• Cost — The amount of money spent on a particular activity, IT service or business unit.
• Credentials — The username and password combination, or other identifier, that is necessary to access a system or device.
• Customer — A person or organization that buys goods or services.
• DemandRequest — A request from a customer of IT to request a new service that IT does not currently offer.
• Diagnosis — A stage in the Incident and Problem lifecycles. The purpose of diagnosis is to identify a workaround for an incident or the root cause of a problem.
• Error — A design flaw or malfunction that causes a failure of one or more CI or IT services, or a mistake made by a person or a faulty process that impacts a CI or IT service.
• Escalation — An activity that obtains additional resources when they are needed to meet service level targets or customer expectations.
• Event — A change of state which has significance for the management of a CI or IT service.
• Graph — The structure of a set of relationships and the objects to which they relate
• Impact — The effect of an event on the status of an IT service or a CI.
• Incident — An unplanned interruption to an IT service or a reduction in the 1uality of an IT service. Also, commonly used to describe the record of an interaction between the service desk and a user.
• Instance — A specific object derived from a class definition.
• Job — An activity performed on a managed device, either manually or through automation.
• KeyPerformanceIndicator (KPI)--A metric that is used to help manage a process, IT service or activity.
• License — A legal instrument governing the usage, distribution, or copying of a piece of software.
• Metric — Something that is measured and reported to help manage a process, IT service or activity. Also, a measured value of a property of a CI.
• Plan — A detailed proposal that describes the activities and resources required to achieve an objective.
• Policy — Formally documented management expectations and intentions.
• Priority — A category used to identify the relative importance of an incident, problem, or change.
• Problem — A cause of one or more incidents
• Process — A structured set of activities designed to accomplish a specific objective.
• Project — A temporary organization required to achieve an objective or other outcome.
• Property — A characteristic of an object for which information is held or metrics are measured or collected.
• PurchaseOrder — A document describing a customer's intent to purchase goods or services.
• Relationship — A connection between two people or things. Also, an association between two instances, classes or relationships.
• Release — A collection of hardware, software, documentation, processes or other components required to implement one or more approved changes to IT services.
• Request — The act of asking for some action (often a service or activity) to take place. Also, the documentation of such a request.
• Resource — A generic term that includes IT infrastructure, people, money or anything else that might help to deliver an IT service.
• Risk — A possible event that could cause harm or loss, or affect the ability to achieve objectives. A risk is measured by the probability of a threat, the vulnerability of the asset to that threat, and the impact it would have if it occurred.
• Role — A set of responsibilities, activities and authorities granted to a person or team.
• Schedule — A set of time periods usually grouped together for some planning purpose.
• Service — A means of delivering value to customers by facilitating outcomes customers want to achieve without the ownership of specific costs and risks.
• Service Offering — The combination of a service with specific service level targets to provide a specific utility and warranty to a customer.
• ServiceCatalog — A database or structured document with information about all live IT services, including those available for deployment.
• ServiceLevel — A measured and reported achievement against one or more service level targets.
• ServiceLevelAgreement (SLA) — An agreement between an IT service provider and a customer that describes the IT service, documents service level targets and describes the responsibilities of the IT service provider and the customer.
• ServiceLevelTarget — A commitment, that is documented in a SLA, that defines a specific service level the IT service provider is obligated to meet
• ServicePortfolio — The complete set of services that are managed by a service provider.
• ServiceRequest — A request from a user for information, or advice or for a Standard Change or for Access to an IT service. Also, A user request for a service that is being offered
• Solution — The resolution of a problem.
• Strategy — A long-term plan designed to achieve some objective.
• Task--An activity that is performed to achieve a specific result, usually by a person.
• Threshold — The value of a metric which should cause an Alert to be generated, or management action to be taken.
• TimePeriod — A defined segment of time.
• Transaction — A discrete function performed by an IT service
• User — An actor (human or software) that utilizes IT services. Someone who uses goods or services.
• Vendor — A third party responsible for supplying goods or services that are required to deliver IT services. Synonymous with supplier.
• Version — An edition, revision or update of a given object (class, instance, attribute, etc.).
• Workflow — A set of activities organized into a process that is meant to achieve some end goal.

Required WSDL binding style 

When you create a web services description language (WSDL) to describe a web service, you must bind the WSDL to the Simple Object Access Protocol (SOAP) message, and the binding style can be either RPC or document, as well as encoded or literal.

Of the different binding styles, BMC requires the document-literal wrapped style. While this style is more complex than others, it is the most interoperable for the following reasons:

• It complies with WS-I Basic Profile (BP) 1.1 (one child per soap:body).
• It is widely accepted.
• The BMC SOA uses it.

The following table summarizes the advantages and disadvantages of the other binding styles. A style must comply with WS-I Basic Profile (BP) 1.1 and have only one child per soap:body element. It should be easily validated so that you can maintain consistency and avoid problems.

 
Summary of advantages and disadvantages of binding styles