This topic provides high-level guidance on building API proxies to call AWS services protected by AWS Identity and Access Management (IAM). The following diagram illustrates the message flow using AWS Lambda as an example. The same flow applies to any IAM-protected service.
Upload the AWS user keys to an encrypted KVM
While Edge provides multiple data persistence options, the most secure place to store your AWS Access Key and Secret Access Key is an Edge encrypted key value map (KVM).
The next section provides information about retrieving the keys to send in your API calls to AWS.
Build the API proxy
Create an API proxy to retrieve the AWS keys from your Edge encrypted KVM and construct a request to AWS. Since you may want to leverage AWS Node.js functions, as well as Edge functions to retrieve encrypted keys, you can create a Node.js API proxy.
See the relevant AWS documentation for information on what to include in calls to specific AWS services. For example, some AWS services require specific HTTP headers.
See the following topics for a Node.js-in-Edge overview, instructions on creating a new Node.js proxy or adding Node.js to an existing proxy, and links to samples.
- Overview of Node.js on Apigee Edge
- Deploying a standalone Node.js app
- Adding Node.js to an existing API proxy
Here's a quick conceptual overview. API proxies often route requests directly to a backend service (for example, https://example.com), as shown in the following sample API proxy TargetEndpoint configuration:
<TargetEndpoint name="default"> <HTTPTargetConnection> <URL>https://example.com</URL> </HTTPTargetConnection> </TargetEndpoint>
However, if you're using Node.js to make calls to a backend, your API proxy hands control off to a Node.js target, shown here:
<TargetEndpoint name="default"> <ScriptTarget> <ResourceURL>node://server.js</ResourceURL> </ScriptTarget> </TargetEndpoint>
You build that Node.js target and its associated resources to get the AWS keys, construct the request, and route it to the appropriate AWS service.
Even though you're using Node.js to make the final request to AWS, you can still attach any desired policies to your API proxy for security, mediation, transformation, and so on.
Retrieving AWS keys from an encrypted KVM
Edge provides an
apigee-access Node.js module that lets you retrieve the AWS
Access Key and Secret Access Key from an Edge encrypted KVM at runtime. You can then include
those keys in your requests to AWS.
- To set up the apigee-access module, see Using the apigee-access module.
- To store and retrieve data from Edge encrypted KVMs, see Working with key value maps.
Proxying AWS Lambda
You can invoke AWS Lambda functions from Edge API proxies over HTTPS. Build an Edge API proxy that uses Node.js to retrieve the AWS user Acccess Key and Secret Access Key and build the request to Lambda. Node.js is useful between Edge and Lambda in other ways as well, since orchestration between the API proxy, Lambda, and other AWS services requires granular coding flexibility that Node.js provides.
In your Node.js code, map individual methods, such as GET and PUT, to specific Lambda functions. Then, when a user sends a request through your API proxy, Edge invokes the corresponding Lambda function. (In Lambda terms, the API proxy is a push event model to Lambda.)
- On your Lambda functions, set the proper execution role and permissions. See the following
topics for more information:
- Create an AWS user that represents your Edge organization, and grant that user appropriate permissions. See Getting started with AWS integration.
- Set appropriate permissions in Lambda: http://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html
- For invoking Lambda functions over HTTPS, the following topic refers to Amazon API
Gateway, but the principles apply to using an Edge API proxy to invoke Lambda functions
- See the Edge Node.js links above for detailed information on using Node.js in Edge to call backend services.
- In your API proxy, prior to the request being forwarded to AWS, you can use Edge policies for inbound security, message mediation, transformation, and so on.
- Edge can invoke Lambda functions and get a responses back in real time by specifying RequestResponse as the invocation type. For information about invocation types, see http://docs.aws.amazon.com/lambda/latest/dg/intro-core-components.html#java-invocation-options.
- Map REST error codes in your API proxies. For example, if a Lambda function throws an
error, the HTTP status code from Lambda will still be 200, but the payload returned will be an
proxy and rebuild an appropriate error to return to the client.
This blog post also has best-practices guidance on handling response errors.
Proxying Amazon S3
Use Amazon S3 in place of FTP or other traditional forms of batch file upload and download. To ensure the successful transfer of large files (10MB maximum in Edge Public Cloud, 3MB in Edge for Private Cloud), you can enable request/response streaming in your API proxy. See the following topics:
- Streaming requests and responses
Streaming is not supported in Node.js on Edge. So if you have streaming enabled on Edge, Edge acts as a passthrough, and you won't be able to use Node.js to retrieve the AWS user keys from the Edge secure store to pass to S3. In that case, you'll need to secure S3 in a way that doesn't require user keys. For more information, see http://docs.aws.amazon.com/AmazonS3/latest/dev/intro-managing-access-s3-resources.html.
Messages larger than supported sizes
If message size exceeds the Edge limit (10MB for Edge Public Cloud and 3MB for Private Cloud), you have a couple of options:
- Use Edge to bypass Edge: Use a Node.js-enabled API proxy to check for message size. If the size exceeds the limit, use the AWS Node.js SDK to generate a temporary URL to post directly to S3, then redirect the large-payload request there.
- Private Cloud: In Edge for Private Cloud, you can change the default 3MB message size limit. For more information, see the Edge Best Practices topic.
Proxying an AWS relational database
Apigee provides connectors to expose relational databases as APIs. You can use the “SQL volos connectors” as a starting point if you need to expose your AWS relational database as a REST API. For more information, see volos-connectors GitHub repository.
If the AWS service you want to proxy is protected by TLS/SSL rather than IAM, see Create API proxies to TLS/SSL-protected services.