aws_api
for DenoFrom-scratch Typescript AWS API client built for Deno.
This library's goal is to codegen type-safe AWS service clients while importing a relatively small number of dependency modules.
Each AWS service has its own module that you can import from several URLs.
To use, you can create a new ApiFactory()
(which manages credentials and such),
and then use it to construct a client for the AWS service API you want to use.
A bare-bones example from demo.ts
:
import { ApiFactory } from 'https://deno.land/x/aws_api/client/mod.ts';
import { STS } from 'https://deno.land/x/aws_api/services/sts/mod.ts';
// Create a service client for AWS Security Token Service
const sts = new ApiFactory().makeNew(STS);
// Call the STS "GetCallerIdentity" API
const identity = await sts.getCallerIdentity();
console.log('You are', identity.UserId, 'in account', identity.Account);
console.log('Identity ARN:', identity.Arn);
Several larger examples in examples/
show concepts such as
launching & managing an EC2 instance, redriving SQS messages from a dead-letter queue,
and writing & reading records within a Kinesis stream.
This aws_api
Deno module is good for:
/extras/s3-presign.ts
for a basic implementation)This module alone is not good for:
/extras/s3-upload.ts
This is NOT a port of the official AWS SDK JS. Though this project can generate a client for every AWS service, I have only personally tested it with a couple dozen services and the bindings might make incorrect assumptions about individual API contracts.
Do not use this module in mission critical stuff. It's intended for automation scripts, quick & dirty pieces of infrastructure, prototype microservices and so on.
If you just want the real, full-fat AWS SDK, check out this aws-sdk-js-v3 issue. A port of the AWS SDK has also been uploaded at /x/aws_sdk.
The exported logic within client/
and encoding/
are liable to change from refactor.
For best upgradability, stick to constructing an ApiFactory
object
and passing it to the services.
The services/
folder contains complete API clients for several key services.
These include S3, DynamoDB, Lambda, S3, and SQS/SNS.
There's also CloudWatch, ECR, Kinesis, KMS, Route53, SES, and STS.
For other services, or to cut down on dependency size by selecting the available actions, you can import from the /x/aws_api Web Service:
import { ApiFactory } from 'https://deno.land/x/aws_api/client/mod.ts';
import { Pricing } from 'https://aws-api.deno.dev/latest/services/pricing.ts';
const pricing = new ApiFactory().makeNew(Pricing);
const { Services } = await pricing.describeServices('AmazonEC2');
console.log('Found', Services.length, 'services:');
for (const serviceItem of Services) {
console.log(' -', serviceItem.ServiceCode);
}
More information can be found on the accompanying Wiki page.
The ApiFactory
constructor accepts optional configuration as an options object.
If you need to change something, pass one of these properties:
credentialProvider
can be a CredentialsProvider
implementation, responsible for loading and refreshing AWS credentials. The default provider is a CredentialsProviderChain
which tries multiple sources. You can pass a customized chain, or even implement a custom provider for your own dynamic-config infrastructure.credentials
can be a particular Credential
implementation. This option disables credential refreshing.region
configures a specific AWS region, disregarding the ambient region from the environment. Useful for being explicit or when working in multiple regions.fixedEndpoint
forces a particular base URL to send all requests to. Useful for MinIO or localstack. Specify a full URL including https://
. This option disables subdomain-style S3 access.endpointResolver
can be an EndpointResolver
which is responsible for selecting endpoint URLs for specific API/region combinations. An AwsEndpointResolver
instance is used by default, which prefers the new .aws
TLD when available. There are also several other resolvers exported by /client/mod.ts
.
AwsEndpointResolver
instance and pass it in here.For example, to access the EC2 API of a particular region:
const ec2_europe = new ApiFactory({
region: 'eu-west-1',
}).makeNew(EC2);
v0.8.1
on 2023-02-26
: hotfixes in extras files
v0.8.0
on 2023-02-26
: codegen v0.4
/std@0.177.0
(except for MD5).
Minimum tested Deno is now v1.22
ReadableStream<Uint8Array>
from S3 GetObject
and similar actions.
Fixes #38/extras/s3-upload.ts
.
Fixes #30/extras/s3-presign.ts
.
Fixes #29v0.7.0
on 2022-05-15
: Client-only changes
v0.6.0
on 2022-01-19
: codegen v0.3
?actions=...
filter
to your import to produce more-concise types./std@0.120.0
Glacier
, ApiGateway
, S3
,
and EC2
S3.SelectObjectContent
)docs=short
as the default. For the least bytes, please specify docs=none
.ApiFactory
, helps with debuggingrest-json
and json
clientsv0.5.0
on 2021-08-27
: codegen v0.2
aws-sdk-js@2.971.0
.makeNew(constructor)
method on ApiFactory
fixedEndpoint
option to ApiFactory
for localstack, minio, etc.AbortSignal
pass-thru/std/uuid
import in favor of crypto.randomUUID()
v0.4.1
on 2021-05-23
: Also fix Deno 1.9 regression for unsigned requests.
v0.4.0
on 2021-05-01
: Deno 1.9 compatibility. Remove most less-common AWS services.
export default
.v0.3.1
on 2021-03-28
: Fix ini-parsing edgecase. Remove zero-field API types.
aws-sdk-js@2.874.0
v0.3.0
on 2021-02-14
: Clean up generation, rename modules to match AWS-SDK
aws-sdk-js@2.839.0
v0.2.1
on 2020-12-21
: Add EC2 instance metadata integration (IMDSv2)
aws-sdk-js@2.814.0
v0.2.0
on 2020-11-07
: Completed bindings for all API services.
aws-sdk-js@2.784.0
v0.1.1
on 2020-11-02
: Generation improvements, most services have been generated.
aws-sdk-js@2.780.0
v0.1.0
on 2020-10-15
: Initial publication with about half of the services bound.
aws-sdk-js@2.768.0
client/
: A handwritten generic AWS API client (credentials, signing, etc)encoding/
: Shared logic for dealing with XML, JSON, & querystringsservices/
: Pre-generated service clients for a handful of important AWS services
demo.ts
: A trivial example of using this library for several servicesexamples/
: Additional detailed examples of using individual servicesPlease reach out on Github Issues about missing features, weird exceptions, or API issues,
or ping dantheman#8546
in the Deno Discord if you just wanna chat about this effort.
All of the clients are compiled from aws-sdk-js
's JSON data files.
The code to generate clients isn't uploaded to /x/
,
so if you want to read through it, make sure you're in the source Git repo.
"Most" of the heavy lifting (such as compiling waiter JMESPaths) runs in the generation step so that the downloaded code is ready to run.
The following clients have been used in actual scripts and should work quite well:
The following credential sources are supported:
~/.aws/credentials
Some individual features that are implemented:
.waitForXYZ({...})
)**.amazonaws.com
(#3)
*.api.aws
Multiple bits are missing:
All API definitions are current as of aws-sdk-js v2.1060.0
.
Class | Module | Protocol |
---|---|---|
CloudWatch |
cloudwatch/mod.ts |
query |
DynamoDB |
dynamodb/mod.ts |
json |
ECR |
ecr/mod.ts |
json |
Kinesis |
kinesis/mod.ts |
json |
KMS |
kms/mod.ts |
json |
Lambda |
lambda/mod.ts |
rest-json |
Route53 |
route53/mod.ts |
rest-xml |
S3 |
s3/mod.ts |
rest-xml |
SESV2 |
sesv2/mod.ts |
rest-json |
SNS |
sns/mod.ts |
query |
SQS |
sqs/mod.ts |
query |
STS |
sts/mod.ts |
query |
For any other services, please check out the code generation web service which performs on-the-fly code generation. You can import the generated URL directly in your application, or download a copy of the file and save it in your source code for safe keeping.
The last version of this library to include every then-current API client
on /x/
is v0.3.1.
Version 0.4.0 of this library stopped including every service's API in the published module. Instead, the code-generation process is running on Deno Deploy and allows importing extremely precise modules, generated on the fly based on multiple configuration options.
Check out this Web Service wiki page for more details on this new URL endpoint. Please report any issues or concerns with this new approach.
For services that are still bundled (SQS, S3, SNS, etc),
the import URL no longer includes an API version
(the @year-month-date
part). Only the most recent API version gets bundled.
The primary class export on each service module is no longer 'default'.
So instead of import SQS from ...
,
you'll do import { SQS } from ....
.