HOW-TO: SMS via Amazon Web Services

(To be followed in order, as indicated below...)

Workflow Walk-through

Now that the REST API is set up and running on your EC2 instance, let's see how well it works. To test it out, we'll walk through the following steps in order:

  1. Create a new topic
  2. Get a topic listing to prove the new topic was created
  3. Add a display name to the topic
  4. Get detailed information on the topic to confirm the display name
  5. Add a new subscription to the topic
  6. Confirm the subscription
  7. List topic subscriptions to prove the subscription was successful
  8. List all subscriptions
  9. Send a new notification message to the topic
  10. Delete the topic
  11. Confirm the deletion by getting a topic listing

Note For each step, I will list the HTTP verb, the URL, and any JSON data that needs to be sent by the user. It is up to you to enter this correctly into your test application. For JSON, data must be sent in the POST, PUT, or DELETE body as raw "application/json" data. There should be a way to specify these settings using whatever application you are using (again, I highly recommend either using the Postman extension to Chrome, or the curl command line utility). Also, for the sake of brevity (because EC2 URLs are severely long), I will use "ec2instance.com" as the domain name in each URL. Last, all responses and ARNs are to be read as examples. Your responses and ARNs will look different, I guarantee it.

Create a new topic

POST URL:

    http://ec2instance.com:3000/sns/v1/topic/
    

JSON:

    {
       "Name": "newtopic"
    }
    

Response:

    {
      "ResponseMetadata": {
        "RequestId": "27d4f5f1-09b3-5b12-a731-babd4dcc24ee"
      },
      "TopicArn": "arn:aws:sns:us-east-1:743696396783:newtopic"
    }
    

Get a topic listing to prove the new topic was created

GET URL:

    http://ec2instance.com:3000/sns/v1/topic/
    

Response:

    {
      "ResponseMetadata": {
        "RequestId": "8ead2e10-d3c9-5565-a570-615c97613490"
      },
      "Topics": [
        {
          "TopicArn": "arn:aws:sns:us-east-1:743696396783:newtopic"
        }
      ]
    }
    

Add a display name to the topic

PUT URL:

    http://ec2instance.com:3000/sns/v1/topic/
    

JSON:

    {
       "attrName": "DisplayName",
       "attrVal": "New Topic",
       "topicArn": "arn:aws:sns:us-east-1:743696396783:newtopic"
    }
    

Response:

    {
      "ResponseMetadata": {
        "RequestId": "a94f48e6-d80f-5abf-97be-07aa9d05cef5"
      }
    }
    

Get detailed information on the topic to confirm the display name

GET URL:

    http://ec2instance.com:3000/sns/v1/topic/arn:aws:sns:us-east-1:743696396783:newtopic
    

Response:

    {
      "ResponseMetadata": {
        "RequestId": "d96247e1-22f5-513b-a58c-08ad67aebe27"
      },
      "Attributes": {
        "Policy": "{"Version":"2008-10-17","Id":"__default_policy_ID","Statement":[{"Sid":"__default_statement_ID","Effect":"Allow","Principal":{"AWS":"*"},"Action":["SNS:Subscribe","SNS:ListSubscriptionsByTopic","SNS:DeleteTopic","SNS:GetTopicAttributes","SNS:Publish","SNS:RemovePermission","SNS:AddPermission","SNS:Receive","SNS:SetTopicAttributes"],"Resource":"arn:aws:sns:us-east-1:743696396783:newtopic","Condition":{"StringEquals":{"AWS:SourceOwner":"743696396783"}}}]}",
        "Owner": "743696396783",
        "SubscriptionsPending": "0",
        "TopicArn": "arn:aws:sns:us-east-1:743696396783:newtopic",
        "EffectiveDeliveryPolicy": "{"http":{"defaultHealthyRetryPolicy":{"minDelayTarget":20,"maxDelayTarget":20,"numRetries":3,"numMaxDelayRetries":0,"numNoDelayRetries":0,"numMinDelayRetries":0,"backoffFunction":"linear"},"disableSubscriptionOverrides":false}}",
        "SubscriptionsConfirmed": "0",
        "DisplayName": "New Topic",
        "SubscriptionsDeleted": "0"
      }
    }
    

The topic is completely set up and ready to roll. Now, set up a new subscription that will receive notifications from the topic.

Add a new subscription to the topic

POST URL:

    http://ec2instance.com:3000/sns/v1/sub/
    

JSON:

    {
        "protocol": "sms",
        "topicArn": "arn:aws:sns:us-east-1:743696396783:newtopic",
        "endpoint": "15035551212"
    }
    

Response:

    {
      "ResponseMetadata": {
        "RequestId": "18cacacd-0ffe-5c5f-b1ff-858148def2e3"
      },
      "SubscriptionArn": "pending confirmation"
    }
    

Confirm the subscription

The subscription ARN will remain at "pending confirmation" until the phone sends a subscription confirmation. That, of course, requires human intervention. After submitting this subscription, a message will be sent to the phone number listed as the "endpoint" asking for a confirmation.

Upon confirmation, the subscription is updated.

List topic subscriptions to prove the subscription was successful

GET URL:

    http://ec2instance.com:3000/sns/v1/sub/arn:aws:sns:us-east-1:743696396783:newtopic
    

Response:

    {
      "ResponseMetadata": {
        "RequestId": "0216af19-e027-58ac-b2f9-e055a78cdc0e"
      },
      "Subscriptions": [
        {
          "SubscriptionArn": "arn:aws:sns:us-east-1:743696396783:newtopic:cc043f86-5499-4d01-8248-ab306d80d405",
          "Owner": "743696396783",
          "Protocol": "sms",
          "Endpoint": "15035551212",
          "TopicArn": "arn:aws:sns:us-east-1:743696396783:newtopic"
        }
      ]
    }
    

List all subscriptions

Just to see if it works, pull a list of all subscriptions using the REST API. The new subscription should be in the list.

GET URL:

    http://ec2instance.com:3000/sns/v1/sub/
    

Response:

    {
      "ResponseMetadata": {
        "RequestId": "351067a1-aabe-536e-99e8-28eded5e2b62"
      },
      "Subscriptions": [
        {
          "SubscriptionArn": "arn:aws:sns:us-east-1:743696396783:newtopic:cc043f86-5499-4d01-8248-ab306d80d405",
          "Owner": "743696396783",
          "Protocol": "sms",
          "Endpoint": "15035551212",
          "TopicArn": "arn:aws:sns:us-east-1:743696396783:newtopic"
        }
      ],
      "NextToken": "AAFfoEQU1TPD4IUnpqafh2D2lCsH8TYiGn0bDR7GV3/iUA=="
    }
    

Send a new notification message to the topic

We have a topic, we have a subscription. It's time, folks: send a notification message.

POST URL:

    http://ec2instance.com:3000/sns/v1/msg/
    

JSON:

    {
        "msg": "Hello from AWS Simple Notification Service!",
        "topicArn": "arn:aws:sns:us-east-1:743696396783:newtopic"
    }
    

Response:

    {
      "ResponseMetadata": {
        "RequestId": "5dedd0d5-6742-5a54-9cf0-9f992fecf602"
      },
      "MessageId": "562a21d7-118d-548d-9d9d-6e9b5923a8db"
    }
    

If everything is working correctly, the notification message should appear on the phone.

Delete the topic

DELETE URL:

    http://ec2instance.com:3000/sns/v1/topic/
    

JSON:

    {
        topicArn": "arn:aws:sns:us-east-1:743696396783:newtopic"
    }
    

Response:

    {
      "ResponseMetadata": {
        "RequestId": "96ceb973-9495-5010-bd14-f63fddf7423d"
      }
    }
    

Confirm the deletion by getting a topic listing

GET URL:

    http://ec2instance.com:3000/sns/v1/topic/
    

Response:

    {
      "ResponseMetadata": {
        "RequestId": "ba357e5c-3488-53f0-b33e-31107d0516cf"
      },
      "Topics": []
    }
    

The empty "Topics" list means we have succeeded.

And that, friends, is how it's done.