Skip to main content
Version: 2.25.2

Getting Started with Aperture

Aperture is available as a managed service, Aperture Cloud, or can be self-hosted within your infrastructure.

1. Sign up to Aperture Cloud

For signing up, head over to Aperture Cloud. For detailed instructions, please refer to our step-by-step guide.

2. Pick your Integration

These are two main modes on how to get started with Aperture.

The Serverless mode is the quickest way to start using Aperture.

Aperture Serverless Architecture Aperture Serverless Architecture

3. Get your API key

In Aperture Cloud, authentication for SDK integrations is handled using API keys. These keys can be found in the Aperture Cloud UI. For detailed instructions on locating API Keys, please refer to the API Keys section.

4. Install SDK and Define Control Points

Aperture provides SDKs for various languages. You can find the SDKs and installation instructions here.

npm install @fluxninja/aperture-js

Connect to Aperture Cloud by creating an Aperture Client with your organization's address and API Key.

import { ApertureClient, FlowStatusEnum } from "@fluxninja/aperture-js";

// Create aperture client
export const apertureClient = new ApertureClient({
address: "ORGANIZATION.app.fluxninja.com:443",
agentAPIKey: "API_KEY",
});

Define a Control Point

Once the SDK is connected to Aperture Cloud, you can create a feature control point anywhere within your code. For example, before executing the business logic of a specific API, you can create a feature control point that can control the execution flow of the API and can reject the request based on the policy defined in Aperture.

Let's create a feature control point in the following code snippet.

async function handleRequest(req, res) {
const flow = await apertureClient.StartFlow("archimedes-service", {
labels: {
api_key: "some_api_key",
},
grpcCallOptions: {
deadline: Date.now() + 300, // ms
},
rampMode: false,
cacheKey: "cache",
});

if (flow.ShouldRun()) {
// Check if the response is cached in Aperture from a previous request
if (flow.CachedValue().GetLookupStatus() === LookupStatus.Hit) {
res.send({ message: flow.CachedValue().GetValue()?.toString() });
} else {
// Do Actual Work
// After completing the work, you can return store the response in cache and return it, for example:
const resString = "foo";

// create a new buffer
const buffer = Buffer.from(resString);

// set cache value
const setResult = await flow.SetCachedValue(buffer, {
seconds: 30,
nanos: 0,
});
if (setResult?.error) {
console.log(`Error setting cache value: ${setResult.error}`);
}

res.send({ message: resString });
}
} else {
// Handle flow rejection
flow.SetStatus(FlowStatusEnum.Error);
}

if (flow) {
flow.End();
}
}

The code snippet below shows how to wrap your Control Point within the StartFlow call while also passing labels and cacheKey to Aperture Agents.

  • The function Flow.ShouldRun() checks if the flow allows the request.
  • The Flow.End() function is responsible for sending telemetry, and updating the specified cache entry within Aperture.
  • The flow.CachedValue().GetLookupStatus() function returns the status of the cache lookup. The status can be Hit or Miss.
  • If the status is Hit, the flow.CachedValue().GetValue() function returns the cached response.
  • The flow.SetCachedValue() function is responsible for setting the response in Aperture cache with the specified TTL (time to live).

This is how you can create a feature control point in your code. The complete example is available here.

5. Create Your Policy

Within the Aperture UI, navigate to the policy in tab in the sidebar menu, and click on the Create Policy button in the top right corner. There you can pick the blueprint that best aligns with your needs. After a few clicks, you'll be directed to a screen where you can input the necessary parameters to generate the policy.

Rate Limiter Blueprint

For more details on how to create a policy, follow our step-by-step guide.