Consolidated Guidance: Describing the Common Services

Synopsis

The service descriptions provide the definition of the functionality and API s to be supported across the Agency's Systems. This document provides some suggestions for what to consider when creating and updating these descriptions.

Guidelines

• Consider the types of users when deciding what to include. The following typical individuals may use the service descriptions:

  • Service Designers and Builders. Those that will implement the services on specific platforms.

  • Procurement Specialists. Those who buy existing products to implement these services, either as discrete information appliances or prepackaged components or solutions , which include purchasing services from third-party application service providers.

  • Quality Assurance. Those individuals who confirm that the implementation of the service conforms to the description, checking for consistency and noting and reconciling discrepancies.

  Generally, application programmers will not use service descriptions directly. Programmers will build mission-oriented applications on top of the implementations that service purchasers, designers, and builders derived from these service descriptions.

• Categorize the service descriptions for each major environment of interest. Different services may be required, especially at the application level.
• Organize the Service descriptions using the service categories of the TRM . This allows for separating the structure of the service definitions from a specific application architecture, allowing each to change independently. Alternate service descriptions may be created for any part of the TRM.
• Business process modeling or use case modeling ( Booch, Rumbaugh, and Jacobson 1999 may be used to identify the elementary processes that end-user application services support, as noted in the Technology Boundary Descriptions .
• Service descriptions define a cohesive set of operations that can be accessed by a client-entity of the application architecture. Limit the service description to only what is essential for someone to reliably implement or purchase a conforming item. What is needed in each circumstance will vary. Services that are provided at the application level should have more narrative descriptions (e.g., an office application), while those intended to be accessed programmatically should be described using more formal notations (an API and accompanying descriptions). Consider the following initial information for each service description:
  • Service Name. An Agency-wide unique name or identifier for the service.
  • Version Information. A unique identifier to distinguish each version of the service definition.
  • Overview. Summarize what the service provides, where and how it is likely to be used, other services it uses, and other high-level characteristics.
  • Service Interface. Describes all the operations, attributes, data types, and exceptions that someone would need to know to access the service. Specify these in a vendor- and implementation-neutral manner, such as by using an IDL ( ISO/IEC 14750 1999 ) or Service Description Language ( W3C 2001 )
  • Service Coupling. Identify coupling between service descriptions.
  • Uses Data Sources. If the service maintains persistent data, identify those data source descriptions by referencing the appropriate part of the Data Sources and Business Rules Reference Set .
  • Static Aspects. When necessary, provide the logical (object) models that the service is built on, using notation such as UML class diagrams ( Booch, Rumbach, and Jacobson 1999 ). Provide only those entities exposed by the interface (e.g., the DOM or objects exposed by the ADO ).
  • Dynamic Aspects. Describe the interactions between the entities in the static model to explain how they can be manipulated. This can be shown using UML sequence or collaboration diagrams ( Booch, Rumbach, and Jacobson 1999 ). Use scenarios to illustrate typical interactions.
  • Reference Implementations. To increase confidence that service design issues have been resolved, one or more reference implementations may be needed. These implementations demonstrate the functionality and other essential properties (e.g., performance) of one or more services. These implementations may not be fully engineered for all quality attributes; developers may use these reference implementations for prototyping. Vendor products may also serve as reference implementations. Reference the source code, executable examples, and accompanying documentation (e.g., a hyperlink to an archive file).
  • Implementation Notes. Guidelines to implement the services may be needed. Provide generic guidelines in the Technical Guidelines Descriptions , as needed.
  • Standards. Identify the basis on which the service is described; this includes any adaptation of the standard. Compile the list of standards and how they apply within the Agency in the A-TARS Standards Reference Set , referenced from each service description.
  • Preferred Implementations. When appropriate, suggest preferred implementations of the services. Keep suggestions to a minimum. Developers should have the opportunity to identify preferred vendors based on commercial considerations when they implement the services (e.g., cost, performance).
  • Changes Expected. Provide any expected modifications and change time frame for the service definition. This is particularly necessary for early adopters of a technology, especially if the underlying standards for the description are still under review and not yet formally approved.
  • Service Packaging. How the services will be packaged may be an assumption for its design and should be communicated, such as using a function/class library, a .dll file, or executable program. Capture generic guidelines in the Technical Guidelines Reference Set.
  • Conformance. Specify guidelines to help ensure conformance to the service definition, from minimum criteria or complete test suites. You also can reference organizations that test for conformance (see the resources for standards organizations).
  • Usage Notes. Provide additional engineering notes not covered above, to help the procurement, developers, or users of the services apply them in a uniform manner.
  • References. Reference specific instances of source documents that provide insight into the definition of the services.
• You may individually package service descriptions as self-contained documents. This will allow parallel development, maintenance, and publication. Services will most likely be developed and used by individuals each having expertise in a particular technical area.
• You can specify the interface and other attributes of the service using automated means to make it easier for individuals to reference the interface definitions, such as using libraries referenced by an integrated development environment.
• Schedule a formal review of the descriptions before final approval. Techniques such as peer reviews ( CMU SEI 1995 ) can be used to structure these reviews. Individuals representing the users of the descriptions should attend. During the reviews, check that the descriptions meets the following objectives:
  • Supports the strategic direction.
  • Supports the properties required for the systems; does not introduce any significant technical risks.
  • Conforms to all referenced documentation.
  • Uses a consistent language to indicate mandatory and optional conditions when implementing the service. Defines all glossary terms and uses them consistently across the service descriptions.

• Evaluate the impact on the applications when changing a service description. These evaluations will take place during the change processing described in the Manage Technical Architecture Activities . Some issues to consider:
  • Retiring the service description, as when a technology is no longer needed by the applications.
  • Allowing for multiple versions of an interface and ensuring that backward compatibility is maintained when components are updated to implement new interfaces. Guidelines may be required on using a version of an interface and determining how different versions of components can simultaneously exist in the production environment.
  • Adding or repackaging services as technology advances; allowing for adaptations in the application and system architectures (e.g., moving to Web services ).
  • Accommodating changes to the appropriate design notes, reference implementations, and other ancillary design information to allow for testing and building applications to the established interfaces.
  • Coordinating changes through the Manage Technical Architecture Activities because the service descriptions may depend on other portions of the A-TARS (e.g., data sources, equipments).
• Place all descriptions under change control, allowing for different versions of each description to be tracked. Components may implement different versions of the interfaces specified in the services. Retire versions when they are no longer needed by the Agency.

Top