		@@ -1,84 +0,172 @@
		# volos-sns connector
		# Volos SQS connector

		The ``volos-sns`` connector lets you use Amazon Simple Notification Service (SNS) through a RESTful API.
		The Volos SQS connector is a Node.js module that lets you use Amazon Simple Queue Service (SQS) through a RESTful API. The module is designed to work on Apigee Edge but can be run anywhere Node.js applications can run. You can use this module without any dependency on Apigee.

		## What is the volos-sns connector?
		### Quick example

		The ``volos-sns`` connector maps SNS operations to RESTful API resources and query parameters. You can perform CRUD operations on objects like subscriptions, publications, and topics.
		This module allows maps SQS operations to RESTful API resources and query parameters. You can perform CRUD operations on objects like messages and queues.

		For example, you might ask for a list of your SNS subscriptions like this:
		For example, you might ask for a list of your SQS subscriptions like this:

		``curl http://localhost:9099/subscriptions``
		``curl http://localhost:9099/queues``

		and get back a JSON response like this:

		```{
		"ResponseMetadata": {
		"RequestId": "d6cc8493-8c95-5389-bbe4-c8a9e4de09ec"
		```
		{
		"action": "GET",
		"params": {
		"qp": {}
		},
		"Subscriptions": [
		{
		"SubscriptionArn": "arn:aws:sns:us-east-1:650324470758:connector-test2:5c3f491e-5c4c-4bed-965f-666c95287211",
		"Owner": "650324470758",
		"Protocol": "sms",
		"Endpoint": "15105526538",
		"TopicArn": "arn:aws:sns:us-east-1:650324470758:connector-test2"
		"path": "/queues",
		"url": "/queues",
		"list": {
		"ResponseMetadata": {
		"RequestId": "799655555-55555-55555-55555-cf14b4bc55555"
		},
		"QueueUrls": [
		"https://sqs.us-east-1.amazonaws.com/650324455555/another2",
		"https://sqs.us-east-1.amazonaws.com/650324455555/another3",
		"https://sqs.us-east-1.amazonaws.com/650324455555/myqueue"
		]
		},
		"timestamp": 1405525899498,
		"duration": 1545,
		"applicationName": "volos-sqs"
		}
		...
		```

		To get a larger set of attributes, use the query parameter ``expand=true``. This option gives you the flexibility to have a small message payload for a subset of fields if those are all that are required. For example:

		# Getting started
		``curl http://localhost:9058/subscriptions?expand=true``

		To use this connector you need two things a correctly configured database connection. Then, you can begin using the API.
		# Installation

		Let's start by configuring a connection and testing it. After that, we'll look at the API itself.
		The ``volos-sqs`` module is designed for Node.js and is available through npm:

		## What do I need to do first?
		```
		$ npm install volos-sqs
		```

		This connector is a Node.js module. So, you must download and install Node.js on your system to use the connector. Follow the instructions at http://nodejs.org/download/.
		# Usage

		Most of our examples use cURL, a utility for making HTTP requests to servers. We recommend you install cURL or have a REST tool like Postman handy.
		There are two examples below, one basic example and one that uses the ``avault`` (Apigee Vault) Node.js module, which is a secure local storage module. Apigee Vault is used to encrypt sensitive login credentials sent to the backend database.

		## How do I install the connector?
		### Simple example without Apigee Vault

		This connector is available through ``npm``. Note that ``npm`` was installed when you installed Node.js.
		The example below shows a simple usage of the ``volos-sqs`` connector using the ``http`` module to proxy requests to the connector.

		1. Create a folder for the connector.
		2. Go to that folder.
		3. Enter: ``npm install volos-sns``
		> Note: In this example, the SQS credentials are specified in plaintext. This is not a best practice.

		## How do I configure my AWS SNS connection?
		The connector needs to know a little bit about your AWS SNS account before it can actually connect. You'll need this information to complete the config:

		```
		var sqsConnector = require('volos-sqs');
		var http = require('http');

		var profile = {
		region: 'myregion'
		accessKeyId: 'myaccesskeyid',
		secretAccessKey: 'mysecretkey'
		};

		var sqsConnectorObject = new sqsConnector.SqsConnector({"profile": profile, "restMap": restMap});

		var svr = http.createServer(function (req, resp) {
		sqsConnectorObject.dispatchRequest(req, resp);
		});

		svr.listen(9089, function () {
		sqsConnectorObject.initializePaths(restMap);
		console.log(sqsConnectorObject.applicationName + ' node server is listening');
		});

		```


		### Simple example using the Apigee Vault for local secure storage

		This example shows the usage of the ``avault`` module to provide a secure local storage option for credentials and endpoint configuration.

		This example assumes you have configured a vault and loaded a configuration profile with a key 'my_profile_key'. See the section "[SQS connection profile](#sqs-connection-profile)" below for a quick example. For a complete description of the ``avault`` module see the [Apigee Vault page on GitHub](https://github.com/apigee-127/avault).

		```
		var sqsConnector = require('volos-sqs');
		var http = require('http');
		var vault = require('avault').createVault(__dirname);

		var sqs;

		vault.get('my-profile-key', function(profileString) {
		if (!profileString) {
		console.log('Error: required vault not found.');
		} else {
		var profile = JSON.parse(profileString);
		var svr = http.createServer(function(req, resp) {
		sqs.dispatchRequest(req, resp);
		});

		svr.listen(9100, function() {
		sqs = new snsConnector.SqsConnector({"profile": profile, configuration: configuration, receiveMessageCallback: receiveMessageCallback});
		sqs.initializePaths(configuration.restMap);
		console.log(sqs.applicationName + ' server is listening');
		});
		}

		function receiveMessageCallback(body, message) {
		var dfd = Q.defer();
		console.log('body: ' + body + ', message: ' + message);
		dfd.resolve('');
		return(dfd.promise);
		}
		});
		```


		# Getting started with your app

		To use this connector you need a correctly configured SQS connection for your AWS SQS account.

		### SQS connection profile

		The SQS configuration profile is used by the connector to establish a connection to the backend SQS account. The profile includes the following fields:

		* region - The AWS region.
		* acessKeyId - The access key ID for your Amazon Web Services SNS account.
		* secretAccessKey - The secret access key for your Amazon Web Services SNS account.
		* acessKeyId - The access key ID for your Amazon Web Services SQS account.
		* secretAccessKey - The secret access key for your Amazon Web Services SQS account.

		Tip: Log in to your SNS account to find your security credentials, including AWS access keys.
		> Tip: Log in to your SQS account to find your security credentials, including AWS access keys.

		Let's walk through the configuration steps:
		Example:
		```
		var profile = {
		region: 'myregion',
		accessKeyId: 'myaccesskeyid',
		secretAccessKey: 'mysecretkey'
		};
		```

		Note: We're going to run a utility called ``vaultcli.js``, which will encrypt your sensitive database login credentials. This utility is an ``npm`` module called ``avault``, which was installed along with this connector. If you're curious, you can find it in the ``node_modules`` folder.
		### Optional: Encrypting the connection profile with Apigee Vault

		1. In a terminal, go to the folder where the ``volos-sns`` module is installed.
		2. Enter this command to encrypt your SNS credentials. Fill in your AWS access keys. Also, specify a name for the vault, which is the name the connector uses to load your encrypted credentials.
		The ``avault`` module provides local, double-key encrypted storage of sensetive information such as credentials and system endpoints. This provides an option to store these kinds of data in a format other than `text/plain`.

		``./node_modules/avault/vaultcli.js --verbose --value='{"region": "my-aws-region", accessKeyId":"my-aws-access-key-id", "secretAccessKey": "my-aws-secret-access-key"}' my-vault-name``
		In order to insert a value into the vault a command-line tool is provided called `vaultcli`. This tool comes with the `avault` module. Here's an example:

		3. Your connector folder now has two new files: ``store.js`` and ``keys.js``. Check to make sure they're present.
		4. Open the file ``server-http.js`` and change the first parameter of the ``vault.get()`` method to the name of the vault you created previously:
		```
		$ vaultcli --verbose --value='{"region"; "myregion", "accessKeyId":"myaccesskeyid", "secretAccessKey": "mysecretaccesskey"}' my-vault-name
		```

		``vault.get('my-vault-name', function(profileString)``
		> Note: These are the same keys that are required in the plaintext version of the profile. If this command completes successfully you will find two new files: `store.js` and `keys.js`. Place them in the root directory of the ``volos-sqs`` module.

		5. Start the HTTP server:
		For more detailed usage of the `avault` module refer to the [Apigee Vault page on GitHub](https://github.com/apigee-127/avault).

		``node server-http``
		# Using the SQS connector

		5. Test the server. In another terminal, or in a REST tool like Postman, enter this command:
		If you run the Node.js server and call the API like this:

		``curl http://localhost:9099``
		``curl http://localhost:9100/``

		6. This call returns usage information for the API:
		The server will return the following API usage information:


		```
		@@ -88,9 +176,10 @@ {
		"Commands": [
		"GET /subscriptions Query Parameters: arn",
		"POST /subscriptions FormVars: arn, phone",
		"DELETE /subscriptions Query Parameters: arn",
		"POST /publications FormVars: message, subject, arn",
		"POST /topics FormVars: name, displayName",
		"GET /topics Query Parameters: arn",
		"GET /platformApplications Query Parameters: arn"
		"GET /messages Query Parameters: queueUrl, maxNumberOfMessages, visibilityTimeout, waitTimeSeconds",
		"POST /messages FormVars: queueUrl, messageBody Optioanl FormVars: delaySeconds",
		"DELETE /messages Query Parameters: queueUrl, receiptHandle",
		"GET /queues/:id",
		"GET /queues Query Parameters: prefix",
		"POST /queues FormVars: queueName",
		"PUT /queues FormVars: queueUrl",
		"DELETE /queues Query Parameters: queueUrl"
		],
		@@ -105,26 +194,13 @@ "Common Optional Parameters": [

		Note that there are some optional query parameters that you can use to filter the results: ``limit`` and ``expand``.

		* limit - Specifies the maximum number of records to fetch. For example: ``?limit=10``.
		* expand - Retrieves expanded records. You can customize both the basic and expanded query strings in the mapping file. For example: ``?expand=true``. By default, this parameter is ``false``.
		For example, to get a list of all of your queues:

		## Checkpoint
		``curl http://localhost:9099/queues``

		You've configured the SNS connector and verified that you have a valid connection. Next, we'll explain how to use the API.
		To get a list of all the messages in a specific queue:

		```
		curl http://localhost:9100/messages?queueUrl=https://sqs.us-east-1.amazonaws.com/555555555555/myqueue
		```

		# Do I need to configure the connector?

		The answer is "no". The file ``configurations.js`` contains the infomation that maps SNS management tasks to well-defined RESTful API resources. You don't need to change this file, but, if you're curious, you can read it to see exactly how the REST API is constructed.

		# Show me how to use the API

		To use this connector, simply refer to the usage information shown previously. For example, to get a list of all of your subscriptions:

		``curl http://localhost:9099/subscriptions``

		To get a list of all the objects in a bucket:

		``curl http://localhost:9099/subscriptions?arn=arn:aws:sns:us-east-1:650324470758:emailsupport:cd7ac02f-07a2-410a-b3c4-6ea6b51cdfb5``

		You might get a response like this:
		@@ -134,14 +210,33 @@
		{
		"ResponseMetadata": {
		"RequestId": "afdad9f2-edad-591f-b71c-95c88b8afca2"
		"action": "GET",
		"params": {
		"qp": {
		"queueUrl": "https://sqs.us-east-1.amazonaws.com/555555555555/myqueue"
		}
		},
		"Attributes": {
		"Owner": "650324470758",
		"ConfirmationWasAuthenticated": "false",
		"Endpoint": "support@apigee.com",
		"RawMessageDelivery": "false",
		"Protocol": "email",
		"TopicArn": "arn:aws:sns:us-east-1:650324470758:emailsupport",
		"SubscriptionArn": "arn:aws:sns:us-east-1:650324470758:emailsupport:cd7ac02f-07a2-410a-b3c4-6ea6b51cdfb5"
		}
		"path": "/messages",
		"url": "/messages?queueUrl=https://sqs.us-east-1.amazonaws.com/555555555555/myqueue",
		"list": {
		"receiveResult": {
		"ResponseMetadata": {
		"RequestId": "5555-5555-5555-ad1e-ec975555364c"
		},
		"Messages": [
		{
		"MessageId": "437b5555-5555-5555-5555-6c44015555",
		"ReceiptHandle": "+eXJYhj5rDo/1645555a7fW5555uezfvnYi9PE6gx4m+43C5555/obWbtYqGi5TA5555ndGsE2UpeIh5555s1J1mjyHEFHCzxxP0G9XxPq9T95555Yxc/BQj5555FKwlXqR5555b2ZZnY++JyD/IGQIJgduD2D5555/Ulc7qD9WKkSoCGQXT5555rycoG1NlJuW9wz/mG75555/YS5555I7NMm2msK2DlArdYXnzD535Jw8G51pR55551EGJ6vEMtgNNXQQ=",
		"MD5OfBody": "9b55552f99d25c52f175b55553c",
		"Body": "Hello world"
		}
		]
		},
		"dequeueResult": {
		"ResponseMetadata": {
		"RequestId": "a61ca5555-5555-5555-5555-6c118555525"
		}
		}
		},
		"timestamp": 1405527082391,
		"duration": 4018,
		"applicationName": "volos-sqs"
		}
		@@ -151,5 +246,3 @@ ````

		To send a push notification to a phone:

		``curl -X POST 'http://localhost:9099/subscriptions?arn=arn:aws:sns:us-east-1:650324470758:emailsupport:cd7ac02f-07a2-410a-b3c4-6ea6b51cdfb5&phone=13035555555'

		@@ -165,2 +258,1 @@

volos-sqs - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics