Docs‎ > ‎Architecture‎ > ‎

Change Management

Change Management is a key consideration for building and maintaining systems, to provide both agility and control.  This section reviews key changes, how they affect API clients, and Best Practices to maximize agility and control.

Key Elements

This page will discuss the elements shown below:
  1. API Clients, and how they are affected by changes to the other elements
  2. Database (schema changes, such as dropping or renaming columns)
  3. Logic changes (reactive logic and security)
  4. Default End Points - created automatically from schema tables, views and procedures
  5. Custom Resources - created by explicit definition, with provisions for join, and column selection / alias

Database Changes

APIs resolve onto database calls, so can affect clients using the API.  The impact is much different for Default vs. Custom Resources, as described below.

Default Resources reflect schema changes

Clients using Default Resources see all schema changes.  New tables/columns may not affect applications, and renamed/deleted objects may or may not affect them, depending of course on whether they were referenced.

Custom Resources affected only by changes to referenced objects

Custom Resources provide an abstraction layer that shields API Clients from many schema changes:
  • Custom APIs are unaffected by new tables / columns

  • Custom APIs are affected by deleted/renamed objects that are referenced.  A Custom Resource is not affected by deleted/renamed objects that are not referenced
You can determine impacts as described below.

Verify Project to identify schema change impacts

Use the API Creator Verify Project function to determine what Custom Resources (and rules) might have been affected by schema changes.  If the objects were merely renamed, you can easily repair the resource by including the new column, and aliasing it to the previous name.

Best Practice: communication, nightly verify

Ideally, the team making schema changes will advise when changes are made.  If this is not practical, you can make the Verify function part of your nightly build.  This will ensure that breakage is detected and can be repaired quickly.

Logic Changes

The sections below discuss how business policy changes impact your system, both API Consumers and existing logic.

Do not affect API Consumers

A key architectural goal was to provide strong Separation of Concerns between the API interface (the data returned) and its semantics for logic and security.  So, logic/security changes are defined on the underlying tables, and automatically re-used over all defined over those tables.

For example, when you make updates through Custom Resources, the system provides automatic Resource/Object Mapping to create logic-enabled row objects from request objects.  So, for example, a Custom Resource defined on Monday will, without changes, enforce additional semantics on Tuesday such as new Validations.

In effect, this Separation enables 3 teams to proceed in parallel:
  • API Consumers
  • API Creators - define Custom Resources
  • Logic Developers - define logic and security

Logic Integration: automatic invocation, ordering

Reactive Logic automates Watch / React processing.  This means that when you add / change rules, new logic is automatically invoked, and executed in an order that reflects the dependencies discovered through logic analysis.

Versioned API Changes

You can version your Custom Resources, to maintain existing interfaces while introducing new ones.

Resources are Logic-aware

And, as noted above, all Resources (unchanged Resources, changed Resources, new Resource versions) share the common underlying logic and security.  Such sharing is automatic, so addresses logic changes that occur even after Resources are created.

Continuous Delivery

Services for Continuous Delivery can promote Change Management, simplifying the ability to move a system from dev to test to production.  Key services are listed below.

Hot Deploy

Since API definitions are settings in the Admin database, there is no code generation and no deploy.  New rules and resources are operational as soon as they are saved.

Scriptable Deploy

In most cases, you will want to test your system before going into production.  While you can use Export / Import to perform such a function manually, in most cases you will want to script it for a repeatable process where you can be certain what is actually deployed (e.g., matches your source control).

Since API Definitions are available through the Admin Restful API, you can script the deployment of an entire system, or just a specific element such as a Custom Resource.