Managing APIs‎ > ‎

Change Management

Change management is a key consideration for building and maintaining systems, to provide both agility and control.

This page discusses the following elements:
  • API clients and how they are affected by changes to the other elements.
  • Database (schema changes, such as dropping or renaming columns).
  • Logic changes (reactive logic and security).
  • Default endpoints, created automatically from schema tables, views, and procedures.
For more information about default endpoints that are created when you connect API Creator to a database, see Customize your API.
  • Custom resources, that you explicitly define, with provisions for join and column selection/alias.
For more information about how to "shape" your API using custom resources, see Customize your API.

Database Changes

APIs resolve onto database calls, so can affect clients using the API. The impact is different for default versus 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 shield API clients from the following schema changes by providing an abstraction layer:
  • 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 impact.

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 how to verify 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, API Creator provides automatic resource/object mapping to create logic-enabled row objects from request objects. So, for example, a custom resource you defined on Monday, without changes, enforces 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.
For more information about resource/object mapping, including how to define multiple custom resources on the same underlying base table, see Logic Execution.

Logic Integration: Automatic Invocation, Ordering

Reactive logic automates watch/react processing. When you add or change rules, 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 maintain existing interfaces while introducing new ones by versioning your custom resources.

For more information about how to version custom resources, see API Versions.

Resources are Logic-aware

All resources (unchanged resources, changed resources, new resource versions) share the common underlying logic and security. The sharing is automatic, so addresses logic changes that occur even after resources are created.

Continuous Delivery

Services for Continuous Delivery (CD) can promote Change Management (CM), 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 (for example, 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.

For more information about how to script the deployment of an entire system, see the Business to Business Example.

Track Changes

You can determine what has changed on the Create, API Properties, Latest changes tab. The following image shows this tab (click to enlarge image):

Reverting Changes

You can make snapshots and roll back to them.

For more information about how to revert changes, see the previous image.