Chapter 4. Service design and documentation policies
This chapter covers
- Making your services self-documenting
- Reusing existing standards and definitions
- Increasing service reusability
- Versioning your services
If you want to create services that can be easily used by your consumers, you need to provide good documentation and versioning strategies. If you don’t have these in place, you’ll either not get anybody to use your service or, with the first upgrade, scare your existing consumers away with breaking changes. When you keep good documentation, versioning, and reuse in mind during the development phase of your service, you make it a lot easier on your consumers; they have a clear set of documentation on how your service should be used and also know the consequences of a version change.
In this chapter we’ll discuss a number of design-time-related policies that can help you in this area. I’ll start by quickly introducing the policies we’ll be discussing in this chapter, and after that we’ll discuss each of these policies in detail, using the case study from chapter 3. A quick overview and short explanation of these policies is shown in table 4.1.