Service discoverability is primarily about answering
one question: Is the functionality that we need already available or do
we need to create or purchase it? In order to answer this question
properly we need to know a number of things, including:
where to search for existing functionality
the purpose, capabilities, and functional boundary of any known service
sufficient information about service availability and service-level guarantees
For this information (Figure 1)
to be available and understandable to a range of project team members,
we need to take the time to ensure that it is sufficiently discoverable
and interpretable. This is what the Service Discoverability principle is concerned with.
In-line Documentation
Service Discoverability
is not just about documenting the service, its capabilities, and
messages, it is about ensuring that whatever documentation is produced
has a high level of communications quality.
Another aspect to consider
is how to organize the documentation and to where it should be
published. Inline annotations can be added to XML schemas and WSDL
definitions using the xsd:annotation and wsdl:documentation elements, respectively:
Example 1.
<xsd:annotation>
<xsd:documentation>
this data model is...
</xsd:documentation>
</xsd:annotation>
<wsdl:documentation>
this service is...
</wsdl:documentation>
|
If you choose to write you
contracts in code using WCF, there is no built-in mechanism for doing
this. The extensibility features of .NET and WCF make it possible to
create custom Documentation and Annotation attributes that can export documentation from your .NET code into generated XML Schema and WSDL definition files.
Note
If
the documentation is placed within XML Schema and WSDL definitions, it
is possible to generate slightly more human readable documents based
upon those files using third-party tools (such as XSDdoc and WSDLdoc)
that output the documentation in HTML format.
REST and Hypermedia
Documenting the resources
and related capabilities for REST services is something that you can
consider doing with WADL or even WSDL 2.0. However, it is generally
expected that REST services be effectively discovered via human-readable
links.
HATEOAS (Hypermedia as the
Engine of Application State) can be used to establish links used by the
service in order to guide service consumers through the process of
making multiple related service invocations. The service adds links to
its response messages to identify a number of suitable subsequent
actions. Service consumers can then traverse these links and dynamically
choose what to do next.
Service Profiles
Throughout its lifespan, information about a service will generally be recorded in a service profile document (Figure 2). Although the service profile is owned by the service custodian and, due to requirements raised by Service Abstraction,
is not typically published in its entirety, there can be opportunities
to make portions of the service profile available as part of the service
SLA or any other form of publicly accessible information.
