API versioning

API urls will be versioned and attached to the anypoint url documentation site.

• whole numbers will be used for API urls
• for the actual API markup, major.minor.patch versioning will be used according to http://semver.org/
• HUD Logical Model changes will trigger major, or at least minor version updates.

Database Schema Versioning

• The postgres relational/operational database schema will be versioned, preferably also using http://semver.org/ conventions. Major versions will occur, probably, for HUD updates, i.e. 2010->2014
• Unlike many conventional HMIS systems, we won't migrate data from old to new database schemas. Instead, data will stay in the original schemas it was collected in, so it doesn't lose its original meaning and context. Some tables and fields will have to remain consistent and linked between schemas versions so cross-version searching can occur. Examples of such fields could be client uuid and personal identifiers, enrollment start/end date, etc... The design considerations for this approach are explained here.
• The Big Data (HBase) data warehouse will be versioned, preferably also using http://semver.org/ conventions. It will change less frequently, and not with each new HUD Logical Model. A field in the HBase warehouse will track which HMIS data standard version is being tracked by each record.

Code versions

The overall data warehouse code will be versioned, preferably also using http://semver.org/ conventions. Major versions will occur, probably, for HUD updates, like 2010->2014

• The Big Data (HBase) data warehouse will be versioned, preferably also using http://semver.org/

Mappings (database schema to API mapping)

A mapping document will relate the relational Database Schema versions (major.minor.patch) to the API markup (major.minor.patch) to the version of code (major.minor.patch) that implements the API on the schema.