@aws-sdk/client-appconfig

Description

AWS SDK for JavaScript AppConfig Client for Node.js, Browser and React Native.

AppConfig feature flags and dynamic configurations help software builders
quickly and securely adjust application behavior in production environments without full
code deployments. AppConfig speeds up software release frequency, improves
application resiliency, and helps you address emergent issues more quickly. With feature
flags, you can gradually release new capabilities to users and measure the impact of those
changes before fully deploying the new capabilities to all users. With operational flags
and dynamic configurations, you can update block lists, allow lists, throttling limits,
logging verbosity, and perform other operational tuning to quickly respond to issues in
production environments.

AppConfig is a tool in Amazon Web Services Systems Manager.

Despite the fact that application configuration content can vary greatly from
application to application, AppConfig supports the following use cases, which
cover a broad spectrum of customer needs:

• 
  

  
  Feature flags and toggles - Safely release new
  capabilities to your customers in a controlled environment. Instantly roll back
  changes if you experience a problem.

  
  


• 
  

  
  Application tuning - Carefully introduce
  application changes while testing the impact of those changes with users in
  production environments.

  
  


• 
  

  
  Allow list or block list - Control access to
  premium features or instantly block specific users without deploying new code.
  

  
  


• 
  

  
  Centralized configuration storage - Keep your
  configuration data organized and consistent across all of your workloads. You can use
  AppConfig to deploy configuration data stored in the AppConfig
  hosted configuration store, Secrets Manager, Systems Manager, Parameter
  Store, or Amazon S3.

  
  

How AppConfig works

This section provides a high-level description of how AppConfig works and how
you get started.

1. Identify configuration values in code you want to manage in the cloud

Before you start creating AppConfig artifacts, we recommend you
identify configuration data in your code that you want to dynamically manage using
AppConfig. Good examples include feature flags or toggles, allow and
block lists, logging verbosity, service limits, and throttling rules, to name a
few.

If your configuration data already exists in the cloud, you can take advantage
of AppConfig validation, deployment, and extension features to further
streamline configuration data management.

2. Create an application namespace

To create a namespace, you create an AppConfig artifact called an
application. An application is simply an organizational construct like a
folder.

3. Create environments

For each AppConfig application, you define one or more environments.
An environment is a logical grouping of targets, such as applications in a
Beta or Production environment, Lambda functions,
or containers. You can also define environments for application subcomponents,
such as the Web, Mobile, and
Back-end.

You can configure Amazon CloudWatch alarms for each environment. The system monitors
alarms during a configuration deployment. If an alarm is triggered, the system
rolls back the configuration.

4. Create a configuration profile

A configuration profile includes, among other things, a URI that enables
AppConfig to locate your configuration data in its stored location
and a profile type. AppConfig supports two configuration profile types:
feature flags and freeform configurations. Feature flag configuration profiles
store their data in the AppConfig hosted configuration store and the URI
is simply hosted. For freeform configuration profiles, you can store
your data in the AppConfig hosted configuration store or any Amazon Web Services
service that integrates with AppConfig, as described in Creating
a free form configuration profile in the the AppConfig User Guide.

A configuration profile can also include optional validators to ensure your
configuration data is syntactically and semantically correct. AppConfig
performs a check using the validators when you start a deployment. If any errors
are detected, the deployment rolls back to the previous configuration data.

5. Deploy configuration data

When you create a new deployment, you specify the following:

• 
  

  An application ID

  
  


• 
  

  A configuration profile ID

  
  


• 
  

  A configuration version

  
  


• 
  

  An environment ID where you want to deploy the configuration data

  
  


• 
  

  A deployment strategy ID that defines how fast you want the changes to
  take effect

  
  

When you call the StartDeployment API action, AppConfig performs the following
tasks:

1. 
   

   Retrieves the configuration data from the underlying data store by using
   the location URI in the configuration profile.

   
   


2. 
   

   Verifies the configuration data is syntactically and semantically correct
   by using the validators you specified when you created your configuration
   profile.

   
   


3. 
   

   Caches a copy of the data so it is ready to be retrieved by your
   application. This cached copy is called the deployed
   data.

   
   

6. Retrieve the configuration

You can configure AppConfig Agent as a local host and have the agent
poll AppConfig for configuration updates. The agent calls the StartConfigurationSession and GetLatestConfiguration API actions and caches your configuration data
locally. To retrieve the data, your application makes an HTTP call to the
localhost server. AppConfig Agent supports several use cases, as
described in Simplified
retrieval methods in the the AppConfig User
Guide.

If AppConfig Agent isn't supported for your use case, you can
configure your application to poll AppConfig for configuration updates
by directly calling the StartConfigurationSession and GetLatestConfiguration API actions.

This reference is intended to be used with the AppConfig User
Guide.

Installing

To install this package, simply type add or install @aws-sdk/client-appconfig
using your favorite package manager:
- npm install @aws-sdk/client-appconfig
- yarn add @aws-sdk/client-appconfig
- pnpm add @aws-sdk/client-appconfig

Getting Started

$3

The AWS SDK is modulized by clients and commands.
To send a request, you only need to import the AppConfigClient and
the commands you need, for example ListApplicationsCommand:

``js
// ES5 example
const { AppConfigClient, ListApplicationsCommand } = require("@aws-sdk/client-appconfig");
`

`ts
// ES6+ example
import { AppConfigClient, ListApplicationsCommand } from "@aws-sdk/client-appconfig";
`

$3

To send a request, you:

- Initiate client with configuration (e.g. credentials, region).
- Initiate command with input parameters.
- Call send operation on client with command object as input.
- If you are using a custom http handler, you may call destroy() to close open connections.

`js
// a client can be shared by different commands.
const client = new AppConfigClient({ region: "REGION" });

const params = { /* input parameters / };
const command = new ListApplicationsCommand(params);
`

#### Async/await

We recommend using await
operator to wait for the promise returned by send operation as follows:

`js
// async/await.
try {
const data = await client.send(command);
// process data.
} catch (error) {
// error handling.
} finally {
// finally.
}
`

Async-await is clean, concise, intuitive, easy to debug and has better error handling
as compared to using Promise chains or callbacks.

#### Promises

You can also use Promise chaining
to execute send operation.

`js
client.send(command).then(
(data) => {
// process data.
},
(error) => {
// error handling.
}
);
`

Promises can also be called using .catch() and .finally() as follows:

`js
client
.send(command)
.then((data) => {
// process data.
})
.catch((error) => {
// error handling.
})
.finally(() => {
// finally.
});
`

#### Callbacks

We do not recommend using callbacks because of callback hell,
but they are supported by the send operation.

`js
// callbacks.
client.send(command, (err, data) => {
// process err and data.
});
`

#### v2 compatible style

The client can also send requests using v2 compatible style.
However, it results in a bigger bundle size and may be dropped in next major version. More details in the blog post
on modular packages in AWS SDK for JavaScript

`ts
import * as AWS from "@aws-sdk/client-appconfig";
const client = new AWS.AppConfig({ region: "REGION" });

// async/await.
try {
const data = await client.listApplications(params);
// process data.
} catch (error) {
// error handling.
}

// Promises.
client
.listApplications(params)
.then((data) => {
// process data.
})
.catch((error) => {
// error handling.
});

// callbacks.
client.listApplications(params, (err, data) => {
// process err and data.
});
`

$3

When the service returns an exception, the error will include the exception information,
as well as response metadata (e.g. request id).

`js
try {
const data = await client.send(command);
// process data.
} catch (error) {
const { requestId, cfId, extendedRequestId } = error.$metadata;
console.log({ requestId, cfId, extendedRequestId });
/**
* The keys within exceptions are also parsed.
* You can access them by specifying exception names:
* if (error.name === 'SomeServiceException') {
* const value = error.specialKeyInException;
* }
*/
}
`

Getting Help

Please use these community resources for getting help.
We use the GitHub issues for tracking bugs and feature requests, but have limited bandwidth to address them.

- Visit Developer Guide
or API Reference.
- Check out the blog posts tagged with aws-sdk-js
on AWS Developer Blog.
- Ask a question on StackOverflow and tag it with aws-sdk-js.
- Join the AWS JavaScript community on gitter.
- If it turns out that you may have found a bug, please open an issue.

To test your universal JavaScript code in Node.js, browser and react-native environments,
visit our code samples repo.

Contributing

This client code is generated automatically. Any modifications will be overwritten the next time the @aws-sdk/client-appconfig` package is updated.
To contribute to client you can check our generate clients scripts.

License

This SDK is distributed under the
Apache License, Version 2.0,
see LICENSE for more information.

Client Commands (Operations List)

CreateApplication

Command API Reference / Input / Output

CreateConfigurationProfile

Command API Reference / Input / Output

CreateDeploymentStrategy

Command API Reference / Input / Output

CreateEnvironment

Command API Reference / Input / Output

CreateExtension

Command API Reference / Input / Output

CreateExtensionAssociation

Command API Reference / Input / Output

CreateHostedConfigurationVersion

Command API Reference / Input / Output

DeleteApplication

Command API Reference / Input / Output

DeleteConfigurationProfile

Command API Reference / Input / Output

DeleteDeploymentStrategy

Command API Reference / Input / Output

DeleteEnvironment

Command API Reference / Input / Output

DeleteExtension

Command API Reference / Input / Output

DeleteExtensionAssociation

Command API Reference / Input / Output

DeleteHostedConfigurationVersion

Command API Reference / Input / Output

GetAccountSettings

Command API Reference / Input / Output

GetApplication

Command API Reference / Input / Output

GetConfiguration

Command API Reference / Input / Output

GetConfigurationProfile

Command API Reference / Input / Output

GetDeployment

Command API Reference / Input / Output

GetDeploymentStrategy

Command API Reference / Input / Output

GetEnvironment

Command API Reference / Input / Output

GetExtension

Command API Reference / Input / Output

GetExtensionAssociation

Command API Reference / Input / Output

GetHostedConfigurationVersion

Command API Reference / Input / Output

ListApplications

Command API Reference / Input / Output

ListConfigurationProfiles

Command API Reference / Input / Output

ListDeployments

Command API Reference / Input / Output

ListDeploymentStrategies

Command API Reference / Input / Output

ListEnvironments

Command API Reference / Input / Output

ListExtensionAssociations

Command API Reference / Input / Output

ListExtensions

Command API Reference / Input / Output

ListHostedConfigurationVersions

Command API Reference / Input / Output

ListTagsForResource

Command API Reference / Input / Output

StartDeployment

Command API Reference / Input / Output

StopDeployment

Command API Reference / Input / Output

TagResource

Command API Reference / Input / Output

UntagResource

Command API Reference / Input / Output

UpdateAccountSettings

Command API Reference / Input / Output

UpdateApplication

Command API Reference / Input / Output

UpdateConfigurationProfile

Command API Reference / Input / Output

UpdateDeploymentStrategy

Command API Reference / Input / Output

UpdateEnvironment

Command API Reference / Input / Output

UpdateExtension

Command API Reference / Input / Output

UpdateExtensionAssociation

Command API Reference / Input / Output

ValidateConfiguration

Command API Reference / Input / Output