Java Reference
In-Depth Information
out what they need to do to consume this with only this section. It should indicate opera-
tion signatures and actions (if present).
▪ Any special items for consumers, such as whether using the service requires an account,
how to authenticate, what headers might be required, if attachments are expected, and so
forth.
▪ The major and minor versions of the service. If this service is deprecated in favor of a
newer version, indicate that along with an end-of-life date (assuming that you know all of
the consumers or are ready to do that). If there are other versions in use, you might link to
them as well.
▪ Optionally, an example of how to consume the service in different languages, if that's ap-
propriate in your organization.
▪ Any related services that may also be of interest, or that might be what the user is really
looking for.
▪ Service-level agreements, including QoS response times, responsible parties, etc.
▪ Any standards or conventions that have been used. Indicate if you are using WS-Address-
ing, MTOM, etc. These might include in-house conventions if that's your audience.
Here are some special considerations to take into account if the service is being developed for
internal consumption, within your organization:
▪ Indicate which compositions may use this service. Often, tools will do this for you, show-
ing graphically what other items in the repository refer to this service and even its attend-
ant documents such as schemas.
▪ Include data resulting from tests that you've executed against the service, so that architects
and administrators can make informed decisions regarding usage levels.
▪ Describe network-related data for the service, such as throughput, response time, availab-
ility, scheduled maintenance windows, etc.
▪ Optionally, include dates the service entered production and dates for each version.
Sophisticated commercial repository tools will handle all of this for you automatically. This
should give you a reasonable start as you consider how to document your services. If you do
not have a vendor tool available for this purpose, consider adding this information as a part
of your build process. If you've used Maven to create your project, this is very easy to add to
the site template and send to an internally available web server. Alternatively, you could con-
sider using a doclet, Docbook, or other markup to generate this structure for you. Docbook is
a good idea if you want your documentation in a variety of formats, such as HTML, PDF, or
