Contract Models: Agile API Documentation (original) (raw)

The Agile Modeling (AM) Method

Sometimes you are in a position to develop a completely new, stand-alone system. If this is the case you should consider yourself amongst the lucky few because the vast majority of developers must often integrate/interface to existing legacy information resources. This could include anything from existing databases or files, existing systems, or even brand-new reusable web services. This article presents a brief overview of legacy system analysis as well as the common problems that you may encounter.The need to work with legacy systems constrains a development team. It reduces your flexibility because you often cannot easily change the legacy systems to reflect the needs of your system. For example, legacy data often doesn’t provide the full range of information required by your system because the existing data does not reflect your new requirements. Similarly, legacy systems which implement functionality that you would like to reuse can often be “almost good enough” but not quite.Agile Modeling (AM) includes the Formalize Contract Models practice which is directly related to legacy system analysis. The basic idea is that when you discover that your system requires access to an information resource then you need to put a “contract model” (often called an external interface specification) in place between your group and the external one.

Examples of contract models include the detailed documentation of an application programming interface (API), a file layout description, an XML DTD or a physical data model describing a shared database. I call them contract models because they effectively form a contract between the owner of an information resource and the owners of other systems that use it – the owner can’t change the system without at least informing everyone else ahead of time or better yet negotiating any changes with them. As with a legal contract, a contract model often requires you to invest significant resources to develop and maintain the contract to ensure that it’s accurate and sufficiently detailed. Your goal is to minimize the number of contract models for your system to conform to the AM principle of traveling light.You often identify potentially legacy information sources that you need to work with as part of your deployment modeling efforts. For each information source that your system must work with you will need to perform some form of legacy system analysis. If you’re lucky accurate documentation already exists for the information resource, and if this is the case your entire analysis effort might be to talk to the system owners and read through the documentation to determine if the information source meets your needs. In many cases you’ll discover that little or no documentation exists or it’s badly out of date. When this is the case either you or the system owner, or both of you, will need to invest the time to analyze and sufficiently document the legacy information source. This activity will often involve working closely with the owners to understand the legacy asset, poring through any pertinent source code, working with modeling tools which support reverse engineering documentation based on the existing source code, or simply working with the legacy information source to determine how it works. This often proves to be a long and arduous process.The most common style of contract model is an external interface (EI) specification which describes how to access an external system. When I’m creating an external interface specification I like to capture the following information: