Resource Technical Notes

This page covers advanced topics for resource development including OpenAPI specifications, authentication methods, pricing models, rate limiting, and troubleshooting common issues.

OpenAPI Specification

Resources must include a complete OpenAPI 3.0 specification defining all endpoints, parameters, request bodies, and response schemas. The platform validates incoming requests against this specification and generates interactive documentation for resource consumers.

Minimal OpenAPI Specification

A minimal OpenAPI specification includes:

{
  "openapi": "3.0.0",
  "info": {
    "title": "My API",
    "version": "1.0.0",
    "description": "API description"
  },
  "servers": [
    {
      "url": "https://api.example.com"
    }
  ],
  "paths": {
    "/endpoint": {
      "get": {
        "summary": "Get data",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  }
}

OpenAPI Capabilities

The OpenAPI specification provides four critical capabilities:

Auto-generated documentation - Interactive API documentation for resource consumers
Type safety - Request and response validation against defined schemas
SDK generation - Automatic client library generation for multiple languages
Clear contracts - Explicit interface definitions between providers and consumers

Authentication Methods

Resources support five authentication mechanisms, each configured through the authentication field and optional authConfig object.

None

none

No authentication required. Use for public APIs or resources with custom authentication logic.

{
  "authentication": "none"
}

API Key

api_key

API key authentication via header or query parameter. Specify the header name and location in authConfig.

{
  "authentication": "api_key",
  "authConfig": {
    "headerName": "X-API-Key",
    "location": "header"
  }
}

Bearer Token

bearer

Bearer token authentication using the Authorization header. Commonly used for JWT tokens and OAuth 2.0 access tokens.

{
  "authentication": "bearer",
  "authConfig": {
    "tokenField": "access_token"
  }
}

Basic Authentication

basic

HTTP Basic authentication with username and password. Credentials are base64-encoded in the Authorization header.

{
  "authentication": "basic",
  "authConfig": {
    "usernameField": "username",
    "passwordField": "password"
  }
}

OAuth 2.0

oauth2

OAuth 2.0 authentication flow with authorization URL, token URL, and scopes. The platform handles token refresh and expiration.

{
  "authentication": "oauth2",
  "authConfig": {
    "authUrl": "https://oauth.example.com/authorize",
    "tokenUrl": "https://oauth.example.com/token",
    "scopes": ["read", "write"]
  }
}

Method Definitions

Each resource method defines an HTTP operation with parameters, request body schema, response schema, and optional cost tracking.

Method Structure

{
  "name": "createUser",
  "httpMethod": "POST",
  "path": "/v1/users",
  "description": "Create a new user account",
  "parameters": {
    "email": {
      "type": "string",
      "required": true,
      "description": "User email address"
    },
    "name": {
      "type": "string",
      "required": false,
      "description": "User full name",
      "default": "Anonymous"
    }
  },
  "response": {
    "type": "object",
    "schema": {
      "id": "string",
      "email": "string",
      "createdAt": "string"
    }
  },
  "cost": 0.01
}

HTTP Methods

Method definitions support all standard HTTP methods (GET, POST, PUT, PATCH, DELETE) and include path parameters using curly brace syntax: /users/{userId}.

Rate Limiting

Resources can define rate limits to control usage and prevent abuse. Rate limits specify the maximum number of requests allowed within a time window.

Rate Limit Configuration

{
  "rateLimit": {
    "requests": 1000,
    "window": "1h"
  }
}

Supported Time Windows

1m - One minute
1h - One hour
1d - One day

Rate Limit Behavior

When a rate limit is exceeded, the platform returns a 429 Too Many Requests response with a Retry-After header indicating when the next request can be made.

Pricing Models

Resources support four pricing models to monetize API access and service usage.

Free

free

No cost for resource usage. Suitable for open APIs, promotional resources, or community-contributed integrations.

{
  "pricing": {
    "model": "free"
  }
}

Pay-Per-Call

pay-per-call

Charges a fixed price per method invocation. Users pay only for actual usage with no recurring fees.

{
  "pricing": {
    "model": "pay-per-call",
    "basePrice": 0.001,
    "currency": "USDC"
  }
}

Subscription

subscription

Charges a recurring monthly fee for unlimited access. Suitable for high-volume use cases with predictable costs.

{
  "pricing": {
    "model": "subscription",
    "basePrice": 10.0,
    "currency": "USDC"
  }
}

Tiered

tiered

Offers multiple subscription tiers with included call quotas and overage pricing. Provides flexibility for different usage levels.

{
  "pricing": {
    "model": "tiered",
    "subscriptionTiers": [
      {
        "name": "Basic",
        "price": 10.0,
        "includedCalls": 1000,
        "overagePrice": 0.01
      },
      {
        "name": "Pro",
        "price": 50.0,
        "includedCalls": 10000,
        "overagePrice": 0.005
      }
    ]
  }
}

Troubleshooting

Authentication Failures

When resource authentication fails, verify the following:

Credentials match the format expected by the authentication type
Authentication type in credentials matches the resource configuration
OAuth 2.0 tokens have not expired (check expiresAt field)
API keys have the necessary permissions for the requested operations
Bearer tokens are valid and not revoked

For OAuth 2.0 resources, the platform automatically refreshes expired tokens using the refresh token. If refresh fails, re-authenticate the resource with new credentials.