How to document web services requirements

Written by Chintan Rajyaguru

Friday, 15 December 2006 12:04

When capturing requirements for a functionality that would be exposed as a web service, it might appear that writing use cases for web service is not any different from writing use cases for a non web service system but as we will see in this and future blogs, there are some decisions to be made:

Where to capture the requirement that the system (or its parts) should be exposed as a web service?

Supplementary specifications: supplementary specifications typically capture non-functional requirements. One may argue that business functionality should be captured in a use case but the fact that it is available as a web service is a non functional requirement and hence should be captured in supplementary specifications. This is also the place where interoperability, security and SLAs related to the web service should be captured. On the flip side, if only parts of the system are available as web service, one may argue that supplementary specification should not have references to parts of the application and web service requirements should be captured in individual use cases for those parts

Use cases: This is another place where it could be indicated whether a given functionality is available as web service. This can be done by capturing web service client as a system user and including that user as the actor on the use case. This is valid because the web service client is typically another system and hence lives outside the boundary of the system. Alternatively, it could be mentioned in the notes or use case description section that the functionality is available as web service

Software Architecture Document: Advocates of keeping requirements strictly implementation agnostic like this option. Typically SAD lists the architecturally significant use cases. This might be a good place to mention the use cases that are available as web services. Remember, at the end of the day, SAD is also driven by requirements! When this option is chosen, care must be exercised to make sure

Web service requirement is communicated to the developers as developers don't tend to keep up to date with SAD

Use case is web service compatible e.g. use case shouldn't say something like, "...system presents a warning: are you sure? User accepts it and submits..."

It is also possible to take a combination of these approaches. Web service related use cases can be identified in SAD, actor can be listed in web service use cases and non functional requirements related to web service can be documented in supplementary specifications.

No matter which approach you take, writing web service use cases has its own challenges, which I will discuss in a future blog. In the meantime, if you work on the requirements/analysis side of an SOA/web service project, you might also want to check out the following articles:

Comments

Add New