Java Reference
In-Depth Information
Documenting Services
Problem
You want to document your web services appropriately so that developers can find them, and
understand what they provide and how they provide it.
Solution
Use your enterprise repository. If you don't have one, there is no single way to do this, but
there are some questions that you should make sure to ask yourself as you document your ser-
vices. We'll examine these now.
Discussion
Given the wide variety of implementations and platforms for services and governance within
any given organization, there is not one single way to do this. You might be running REST ser-
vices with PHP clients, with OpenLDAP as a service repository. Or you could have services
implemented with JAX-WS using a vendor platform for your registry/repository such as Soft-
ware AG's CentraSite, or IBM WebSphere Service Registry and Repository, or you may be
using Apache Scout for UDDI. The capabilities provided by these different products and plat-
forms obviates any discussion of a single way to document services. But there are some things
to keep in mind as general rules, which you can then adapt for your organization.
Here is a list of things you should include in your documentation:
▪ The name of the service.
▪ The general type of service: a business process, a data service representing a business en-
tity, a functional service, and so on.
▪ A succinct statement (one sentence) indicating the purpose of the service.
▪ A descriptive overview that acts as an executive summary. This makes browsing services
easier for project managers and analysts.
▪ A specification that is a business analyst could understand. It should be detailed enough
for the analyst to be able to decide if a service is appropriate for use within a given solu-
tion.
▪ A technical specification. This is written for an audience of developers who need to know
how to use your service. Keep this discussion client-facing; they should be able to figure
Search WWH ::




Custom Search