Skip to content

Web Service

Jump to bottom
Daniel Lamando edited this page Jan 19, 2022 · 7 revisions

Version v0.4.0 of this library introduced a new codegen strategy of producing Typescript modules "just in time" when they are requested from a server. This reduces the size of the repository, while allowing the modules to include more detail if desired (such as the related AWS Documentation text). The imported modules can also be filtered to include only the required API calls.

The web service can be found here: https://aws-api.deno.dev/ and is hosted on Deno Deploy.

Please remember that this is an unofficial third-party effort and has no relation to AWS.

Import URLs

The most basic form of an import is as so:

// for Simple Queue Service
import { SQS } from "https://aws-api.deno.dev/v0.2/services/sqs.ts";
// for Simple Storage Service
import { S3 } from "https://aws-api.deno.dev/v0.2/services/s3.ts";

Consult the web service directory for a full list of the available APIs and their filenames.

To use API definitions from a specific aws-sdk-js v2 release, specify it in the URL:

// specific revision of Simple Queue Service API
import { SQS } from "https://aws-api.deno.dev/v0.2/[email protected]/sqs.ts";

Some services (for example RDS) have multiple SDK definitions, identified by ISO date strings. These can be specified as well if you need it. When not specified, the most recent definitions are used by default.

// specific revision and 'API Version' of Simple Queue Service API
import { SQS } from "https://aws-api.deno.dev/v0.2/[email protected]/[email protected]";

Codegen Revisions

When an aws-sdk-js version is not specified in the URL, a fixed version is used based on the codegen revision (the first part of the path). The below table shows the default API definition versions:

Revision Status date added /x/aws_api /std aws-sdk-js codegen
v0.1 Legacy 2021-05-01 v0.4.0 0.95.0 v2.895.0 git main
v0.2 Stable 2021-08-31 v0.5.0 0.105.0 v2.971.0 git main
v0.3 Default 2021-01-19 v0.6.0 0.120.0 v2.1060.0 git main

Most revisions will likely be little more than version bumps. However, at some point the codegen may be changed to produce notably different interfaces, at which point a snapshot of the latest previous codegen will be made in order to continue serving requests for previous revisions.

In any case, the API definitions will be fetched from Github and stored in a long-term cache when they are first requested. This should help tolerate Github downtime :)

Parameters

Use ? query parameters to customize your generation experience.

  • ?docs=<none/short/full> configure doc-comments.
    • none for the smallest bundle, no comments are included. Handy if you already know the AWS service[s] you are using.
    • short for the first 'line' of documentation text. This is pretty cheap to include, it doesn't include too much detail.
    • full includes every word that AWS puts into the API definitions. It's not unusual to see multiple paragraphs written for a single API operation. Useful if you want to have as much information as possible available in-editor.
  • ?actions=GetObject,PutObject sets up a passlist of specific API actions to include. The list is comma-seperated and also supports basic globbing such as Describe*. Recommended for large API surfaces like EC2 or S3, or in general when typecheck time seems too long after importing a few API modules.

Tips

  • If your use-case doesn't agree with loading source code from a generation endpoint, feel free to download modules into your codebase, vendor-style.

  • When viewing modules in Deno's Docs service, include %3Fdocs=full in the URL to request full doc-text from the generation service. For example: SQS API Documentation

Clone this wiki locally