Versioned Governance

Versioned GovernanceREST resources and components are meant to be used in more than one application. Organizations should plan for the incremental enhancement of resources over a long deployment lifetime. Essentially, organizations planning to build a robust, stable, and extensible REST resource need to treat resources as “products.”

What does treating a resources as a “product” mean to our IT organization?

  1. Each produced resource must have a regular and well-defined release cycle. The release cycle should occur often enough to meet consumer needs on a timely basis. However, not so often as to churn existing consumers. Typically, an appropriate release cycle for most organizations is between three and six months, which allows organizations to meet new resource needs without unduly disrupting existing applications. When multiple versions of a resource are released, consider defining the life-cycle states for your resources:

Under Development: Available for requirements gathering and application development team planning purposes

–  Production: Mainline version for use in new development

–  Retired: Still in use by existing applications but not allowed for use by new apps

–  Obsolete: All applications should be migrated off this version; version metadata is maintained for traceability/audit purposes only

2. Resources must preserve backward compatibility when possible. Deprecation techniques (where obsolete operations are identified, and notice given to consumers operations will be removed from resource interfaces in future releases) gives existing consumers time to migrate to newer resource releases. Additionally, resource providers should offer n-1 version support at a minimum. All resources provided in a prior version (except ones marked as deprecated) should be preserved intact in the current version. Moreover, consider offering a “grace period” for both resource versions during deployment to allow consumers to make necessary changes while integrating to the new resource version. Dynamic run-time binding techniques via Web resources management infrastructure also simplify the migration process from an old-to-new resource version.

3. The enterprise architecture and resource review teams need to establish mechanisms for gathering requirements from current and potential “customers.” Consider establishing a “product manager” role within the organization, one that manages the aggregate set of business requirements for the resource, and works to prioritize requirements with its current, and potential customers.

Again, a well-designed discovery mechanism helps an organization manage the lifetime of resource versions with automated notifications, and embedded discussion forums for requirements gathering. Further, analysis through filter-based search capabilities, which expose resources to potential consumers based on a resources state, also result from a well-designed discovery mechanism.