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 discusses the following elements:
  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 different for Default vs. Custom Resources.

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 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 the impacts.

Verify Project to identify schema change impacts

Verify your API project to determine what custom resources (and rules) might have been affected by schema changes. If the objects were renamed, you can repair the resource by including the new column, and aliasing it to the previous name.

For more information about verifying API projects, see Data Sources.

Best Practice: Communication, Nightly Verify

Ideally, the team making schema changes advises when changes are made. If this is not practical, you can make verifying the API project part of your nightly build. This ensures that breakage is detected and can be repaired quickly.

Logic Changes

The following sections describe how business policy changes impact your system, both API consumers and existing logic.

Do not affect API Consumers

A key architectural goal is to provide strong Separation of Concerns between the API interface (the data returned) and its semantics for logic and security. 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 you defined on Monday will, without changes, enforce additional semantics on Tuesday such as new validations.

In effect, this Separation enables the following 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. When you add or change rules, Live API Creator automatically invokes new logic and executes the logic in an order that reflects the dependencies discovered through logic analysis.

For more information:

Versioned API Changes

You can version your custom resources, to maintain existing interfaces while introducing new ones.

For more information about API project versioning, see API versions.Versions

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. The following are the key services:

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 perform such a function manually using export/import, in most cases you will want to be certain what is actually deployed (e.g., matches your source control) by 
scripting it for a repeatable process.

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.