Contract Models: Agile API Documentation

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:

  • Identifier. A unique identifier, for example EI-1701.
  • Description. A couple of sentences or a paragraph describing the external system interface.
  • System owner. The name(s) and contact information of the people who own the system. Include both the team leader and the technical contact.
  • Type. The type of interface, e.g., XML, JMS, Java API, flat file transfer, etc
  • Direction. List the direction of the transfer – Outwards, inwards, or bi-directional.
  • Frequency. Approximately how often this interface is exercised, e.g., once a week, 500 times a day, etc.
  • Timing. Describe when the interface is used, for example 24/7, once a night at 2 a.m., and so on.
  • Transfer rate. List known or required transfer rates, e.g., the file will be 50 megabytes on average or the records will be 125 bytes each.
  • Security. List known security issues, e.g., is a login required, is the source system protected by a firewall, is a secure socket layer used, “¦
  • Format. Describe in detail the format of any data transfer. You may simply reference an XML schema definition, describe a file record layouts, or describe a C API. The information in this section will vary depending on the interface specifics.
  • Issues. List any “to dos”, concerns to be addressed, and so on.
  • Decisions. List any important decisions made during the development of this interface.