How to be a good web service? Documentation

Good documentation of web service can help clients to design related behavior. At high level, a web service component comprises two parts, request and response.

The documentation for request.

A web request include URI address, query parameters, headers and body.

URI address, for a good web service, the documentation of the URI should include the composition of the URI. For example,  Windows Azure Service Bus,  the service URI is assembled from a base URI which is specific to each region, a namespace which is determined by customer at the time of creating of the account, the name of the entity, for example the queue, topic or subscription.The documentation should include the meaning of each component,  how/where to obtain each component, and the rule to assemble the address from these components.

Query parameters, they are the parameters passed into the request as the query string appending to the address after a ? (question mark). Query parameters include mandatory query parameter and optional query parameter, the documentation should include the composition of each set and meanings of each parameter. In addition, it should also include the type of the error when each of the mandatory parameters is missing or out of range.

Headers,  headers are a set of name value pairs sent at the beginning of the HTTP request. Similar to query parameters, documentation of them should include the set of the mandatory and optional headers, the meaning of each header, the valid range and the error message when they are missing or out of range.

body, the schema of the body should be documented if the body is an XML or JSON. The error message for each error condition based on the incorrect request should be documented as well.

 

The documentation of the response.

The response also have header and body. The documentation should include the type of the header, the permitted values of the headers and their meaning, the schema of the body.

 

Good documentation provides convenience for developers using different language to communicate with the web service.