Core Concepts
ApiCharge introduces several key concepts that form the foundation of its monetization system. Understanding these concepts is essential for effectively configuring and utilizing the platform.
ApiCharge Subscriptions
An ApiCharge Subscription is a time-bound grant of access to a specific API route with clearly defined quality of service parameters. The key differentiator is that the subscription is for a specific quality of service, guaranteed by the network component, and can be for minutes or months. This allows for flexible pricing control where service level design and pricing can be changed without impacting existing customers. Furthermore, this integration between the network service provision and pricing strategy itself allows for new types of flexibility, such as going from a monthly access to pay-per-use at a whim.
Key characteristics of ApiCharge Subscriptions include:
- Time-bound: Each ApiCharge Subscription has a specific start and end time
- Route-specific: Access is granted to a particular API route or service
- QoS-defined: Clear quality of service parameters using rate limiters
- Cryptographically secure: All grants are digitally signed
- Autonomous: Designed for machine-to-machine payments
Client → Quote Request → Route Selection → Purchase Token → Access Service with QoS
Quotes
A quote is a digitally signed offer for access to a specific route with defined quality of service parameters at a specified price. Quotes are generated by the ApiCharge server and have a limited validity period.
Quote properties include:
- Route identifier: The specific API route the quote is for
- Rate limiters: Quality of service parameters (call counts, data limits, etc.)
- Price: Cost in cryptocurrency (Stellar XLM)
- Duration: The time period for the ApiCharge Subscription
- Digital signature: Cryptographic proof of authenticity
- Expiration: When the quote itself expires (not the same as duration)
Clients can request quotes from the server, select the desired quote based on their needs, and then proceed with the purchase process.
Access Tokens
After purchasing an ApiCharge Subscription, the client receives an access token. This token is a signed credential that grants the bearer access to the specified route with the agreed quality of service parameters.
Access token components:
- Token identifier: Unique ID for the specific access grant
- Route identifier: The service route the token grants access to
- Client identifier: The client/account that purchased access
- Validity period: Start and end time for the access grant
- Quality of service: Embedded rate limiting parameters
- Cryptographic signature: Proof of authenticity and integrity
The access token is presented with each request to the protected service, typically in an HTTP header or cookie. ApiCharge validates the token and enforces the specified rate limits in real-time.
Rate Limiters
Rate limiters are the mechanisms that enforce quality of service parameters for ApiCharge Subscriptions. They define exactly what a client is allowed to do during their access period.
ApiCharge supports several types of rate limiters:
- Call Count: Limits the total number of API calls
- Data Limits: Controls the total data transfer (upload/download)
- Stream Rate: Defines maximum bandwidth (bytes per second)
- Credits: Implements a flexible credit-based consumption model
Rate limiters can be combined to create sophisticated service tiers with precisely defined parameters. For example, a "Basic" tier might have lower call counts and data limits than a "Premium" tier.
Routes
Routes in ApiCharge define the mapping between client requests and backend services. Each route represents a specific API or service that can be monetized.
Routes are configured with:
- Route ID: A unique identifier for the route
- Match criteria: Path, host, or method patterns that determine which requests match this route
- Destination: The backend service where requests should be proxied
- Metadata: Additional information about the route such as descriptions, categories, etc.
Routes are defined in the ApiCharge configuration and are used to generate quotes for clients.
Stellar Integration
ApiCharge uses the Stellar blockchain and Soroban smart contracts to handle the payment and verification aspects of ApiCharge Subscriptions. This integration provides:
- Secure payments: Fast, low-cost transactions
- Smart contract verification: Ensures payment validity
- Public auditability: All transactions are recorded on-chain
- Digital signatures: Used to verify quotes and access tokens
The Stellar integration happens behind the scenes but is a fundamental part of how ApiCharge secures the monetization process.
Protocol Flow
The complete ApiCharge workflow combines these concepts into a coherent protocol:
- Quote Request: Client requests service quotes from the ApiCharge server
- Quote Selection: Client selects a route with desired quality of service
- Purchase Instruction: Client requests purchase instructions for the selected quote
- Payment: Client authorises the payment
- ApiCharge Subscription Issuance: Server verifies payment and issues an access token
- Service Access: Client uses the token to access the service with agreed QoS parameters
This protocol flow ensures secure, verifiable transactions while providing flexible monetization options for API providers.
Next Steps
Now that you understand the core concepts behind ApiCharge, you can explore:
- Configuration Overview to learn how to set up ApiCharge
- Routes to understand how to define and manage your services
- Rate Limiters to learn about quality of service controls
- Protocol for a deeper dive into the technical details