refactor(ssm): API cleanups

BREAKING CHANGE: `ParameterStoreString` has been removed. Use `StringParameter.fromStringParameterAttributes`.
* **ssm:** `ParameterStoreSecureString` has been removed. Use `StringParameter.fromSecureStringParameterAttributes`.
* **ssm:** `ParameterOptions.name` was renamed to `parameterName`.

packages/@aws-cdk/aws-ssm/lib/index.ts

@@ -1,5 +1,4 @@
 export * from './parameter';
-export * from './parameter-store-string';
 
 // AWS::SSM CloudFormation Resources:
 export * from './ssm.generated';

packages/@aws-cdk/aws-ssm/lib/parameter.ts

@@ -1,5 +1,5 @@
 import iam = require('@aws-cdk/aws-iam');
-import { CfnDynamicReference, CfnDynamicReferenceService, Construct, Fn, IResource, Resource, Stack, Token } from '@aws-cdk/cdk';
+import { CfnDynamicReference, CfnDynamicReferenceService, Construct, Fn, IResource, Resource, Stack, Token, CfnParameter } from '@aws-cdk/cdk';
 import ssm = require('./ssm.generated');
 
 /**
@@ -86,9 +86,9 @@ export interface ParameterOptions {
   /**
    * The name of the parameter.
    *
-   * @default a name will be generated by CloudFormation
+   * @default - a name will be generated by CloudFormation
    */
-  readonly name?: string;
+  readonly parameterName?: string;
 }
 
 /**
@@ -145,8 +145,35 @@ abstract class ParameterBase extends Resource implements IParameter {
 }
 
 const STRING_PARAM_TYPE = 'String';
+const SECURE_STRING_PARAM_TYPE = 'SecureString';
 const STRINGLIST_PARAM_TYPE = 'StringList';
 
+export interface ParameterAttributes {
+  /**
+   * The name of the parameter store value
+   */
+  readonly parameterName: string;
+
+  /**
+   * The version number of the value you wish to retrieve.
+   *
+   * @default The latest version will be retrieved.
+   */
+  readonly version?: number;
+}
+
+export interface SecureStringParameterAttributes {
+  /**
+   * The name of the parameter store value
+   */
+  readonly parameterName: string;
+
+  /**
+   * The version number of the value you wish to retrieve. This is required for secure strings.
+   */
+  readonly version: number;
+}
+
 /**
  * Creates a new String SSM Parameter.
  * @resource AWS::SSM::Parameter
@@ -156,11 +183,31 @@ export class StringParameter extends ParameterBase implements IStringParameter {
   /**
    * Imports an external string parameter.
    */
-  public static fromStringParameterName(scope: Construct, id: string, stringParameterName: string): IStringParameter {
+  public static fromStringParameterAttributes(scope: Construct, id: string, attributes: ParameterAttributes): IStringParameter {
+    if (!attributes.parameterName) {
+      throw new Error(`parameterName cannot be an empty string`);
+    }
+
+    const stringValue = attributes.version
+      ? new CfnDynamicReference(CfnDynamicReferenceService.Ssm, `${attributes.parameterName}:${attributes.version}`).toString()
+      : new CfnParameter(scope, `${id}.Parameter`, { type: 'AWS::SSM::Parameter::Value<String>', default: attributes.parameterName }).valueAsString;
+
     class Import extends ParameterBase {
-      public readonly parameterName = stringParameterName;
+      public readonly parameterName = attributes.parameterName;
       public readonly parameterType = STRING_PARAM_TYPE;
-      public readonly stringValue = new CfnDynamicReference(CfnDynamicReferenceService.Ssm, stringParameterName).toString();
+      public readonly stringValue = stringValue;
+    }
+
+    return new Import(scope, id);
+  }
+
+  public static fromSecureStringParameterAttributes(scope: Construct, id: string, attributes: SecureStringParameterAttributes): IStringParameter {
+    const stringValue = new CfnDynamicReference(CfnDynamicReferenceService.SsmSecure, `${attributes.parameterName}:${attributes.version}`).toString();
+
+    class Import extends ParameterBase {
+      public readonly parameterName = attributes.parameterName;
+      public readonly parameterType = SECURE_STRING_PARAM_TYPE;
+      public readonly stringValue = stringValue;
     }
 
     return new Import(scope, id);
@@ -180,7 +227,7 @@ export class StringParameter extends ParameterBase implements IStringParameter {
     const resource = new ssm.CfnParameter(this, 'Resource', {
       allowedPattern: props.allowedPattern,
       description: props.description,
-      name: props.name,
+      name: props.parameterName,
       type: STRING_PARAM_TYPE,
       value: props.stringValue,
     });
@@ -228,7 +275,7 @@ export class StringListParameter extends ParameterBase implements IStringListPar
     const resource = new ssm.CfnParameter(this, 'Resource', {
       allowedPattern: props.allowedPattern,
       description: props.description,
-      name: props.name,
+      name: props.parameterName,
       type: STRINGLIST_PARAM_TYPE,
       value: props.stringListValue.join(','),
     });

packages/@aws-cdk/aws-ssm/test/integ.parameter-store-string.lit.ts

@@ -7,7 +7,7 @@ class CreatingStack extends cdk.Stack {
     super(scope, id);
 
     new ssm.StringParameter(this, 'String', {
-      name: '/My/Public/Parameter',
+      parameterName: '/My/Public/Parameter',
       stringValue: 'abcdef'
     });
   }
@@ -20,14 +20,14 @@ class UsingStack extends cdk.Stack {
     /// !show
     // Retrieve the latest value of the non-secret parameter
     // with name "/My/String/Parameter".
-    const stringValue = new ssm.ParameterStoreString(this, 'MyValue', {
+    const stringValue = ssm.StringParameter.fromStringParameterAttributes(this, 'MyValue', {
       parameterName: '/My/Public/Parameter',
       // 'version' can be specified but is optional.
     }).stringValue;
 
     // Retrieve a specific version of the secret (SecureString) parameter.
     // 'version' is always required.
-    const secretValue = new ssm.ParameterStoreSecureString({
+    const secretValue = ssm.StringParameter.fromSecureStringParameterAttributes(this, 'MyValue', {
       parameterName: '/My/Secret/Parameter',
       version: 5
     });

packages/@aws-cdk/aws-ssm/test/test.parameter-store-string.ts

@@ -9,7 +9,7 @@ export = {
     const stack = new cdk.Stack();
 
     // WHEN
-    const ref = new ssm.ParameterStoreString(stack, 'Ref', {
+    const ref = ssm.StringParameter.fromStringParameterAttributes(stack, 'Ref', {
       parameterName: '/some/key',
       version: 123
     });
@@ -25,21 +25,21 @@ export = {
     const stack = new cdk.Stack();
 
     // WHEN
-    const ref = new ssm.ParameterStoreString(stack, 'Ref', {
+    const ref = ssm.StringParameter.fromStringParameterAttributes(stack, 'Ref', {
       parameterName: '/some/key',
     });
 
     // THEN
     expect(stack).toMatch({
       Parameters: {
-        RefParameter407AF5C8: {
+        RefParameter: {
           Type: "AWS::SSM::Parameter::Value<String>",
           Default: "/some/key"
         }
       }
     });
 
-    test.deepEqual(stack.resolve(ref.stringValue), { Ref: 'RefParameter407AF5C8' });
+    test.deepEqual(stack.resolve(ref.stringValue), { Ref: 'RefParameter' });
 
     test.done();
   },
@@ -49,10 +49,10 @@ export = {
     const stack = new cdk.Stack();
 
     // WHEN
-    const ref = new ssm.ParameterStoreSecureString({
+    const ref = ssm.StringParameter.fromSecureStringParameterAttributes(stack, 'Ref', {
       parameterName: '/some/key',
       version: 123
-    });
+    }).stringValue;
 
     // THEN
     test.equal(stack.resolve(ref), '{{resolve:ssm-secure:/some/key:123}}');
@@ -66,10 +66,10 @@ export = {
 
     // WHEN
     test.throws(() => {
-      new ssm.ParameterStoreString(stack, 'Ref', {
+      ssm.StringParameter.fromStringParameterAttributes(stack, 'Ref', {
         parameterName: '',
       });
-    }, /parameterName cannot be empty/);
+    }, /parameterName cannot be an empty string/);
 
     test.done();
   },

packages/@aws-cdk/aws-ssm/test/test.parameter.ts

@@ -3,6 +3,7 @@ import cdk = require('@aws-cdk/cdk');
 import { Stack } from '@aws-cdk/cdk';
 import { Test } from 'nodeunit';
 import ssm = require('../lib');
+import { version } from 'punycode';
 
 export = {
   'creating a String SSM Parameter'(test: Test) {
@@ -13,7 +14,7 @@ export = {
     new ssm.StringParameter(stack, 'Parameter', {
       allowedPattern: '.*',
       description: 'The value Foo',
-      name: 'FooParameter',
+      parameterName: 'FooParameter',
       stringValue: 'Foo',
     });
 
@@ -60,7 +61,7 @@ export = {
     new ssm.StringListParameter(stack, 'Parameter', {
       allowedPattern: '(Foo|Bar)',
       description: 'The values Foo and Bar',
-      name: 'FooParameter',
+      parameterName: 'FooParameter',
       stringListValue: ['Foo', 'Bar'],
     });
 
@@ -128,12 +129,15 @@ export = {
     test.done();
   },
 
-  'StringParameter.fromName'(test: Test) {
+  'StringParameter.fromStringParameterAttributes'(test: Test) {
     // GIVEN
     const stack = new Stack();
 
     // WHEN
-    const param = ssm.StringParameter.fromStringParameterName(stack, 'MyParamName', 'MyParamName');
+    const param = ssm.StringParameter.fromStringParameterAttributes(stack, 'MyParamName', {
+      parameterName: 'MyParamName',
+      version: 2
+    });
 
     // THEN
     test.deepEqual(stack.resolve(param.parameterArn), {
@@ -148,7 +152,7 @@ export = {
     });
     test.deepEqual(stack.resolve(param.parameterName), 'MyParamName');
     test.deepEqual(stack.resolve(param.parameterType), 'String');
-    test.deepEqual(stack.resolve(param.stringValue), '{{resolve:ssm:MyParamName}}');
+    test.deepEqual(stack.resolve(param.stringValue), '{{resolve:ssm:MyParamName:2}}');
     test.done();
   },