API Gateway Patterns and Rate Limiting in OutSystems

OutSystems exposed REST APIs provide by default: - CORS headers (Access-Control-Allow-Origin: *) - Basic and Custom Authentication via OnAuthentication callback - HTTPS (SSL/TLS) on OutSystems Cloud environments - Auto-generated OpenAPI/Swagger documentation - Request/response logging in Service Center → Monitoring → Integrations OutSystems does NOT provide: - Rate limiting or request throttling - Request/response transformation at the network edge - API key lifecycle management (issuance, rotation, quotas) - Developer portal with self-service API key sign-up - DDoS protection at the API layer - Geographic routing or latency-based routing - Monetization and billing per API call For internal integrations (other OutSystems modules, trusted internal services), built-in authentication is usually sufficient. For external APIs exposed to third-party developers, a gateway is required.

For cases where an external gateway is not available, implement rate limiting directly in OutSystems using a database counter pattern. First, create an entity: Data tab → Entities → Database → right-click → Add Entity. Name it ApiRateLimit with attributes: - ApiKeyId (ApiKey Identifier) - WindowStart (DateTime) - RequestCount (Integer) - MaxRequests (Integer, default: 100) - WindowSeconds (Integer, default: 60) In the OnAuthentication action (Logic tab → Integrations → REST → [YourAPI] → OnAuthentication), after the API key is validated, add: Start → ... validate API key ... → [GetCurrentWindow: Aggregate, Filter: ApiRateLimit.ApiKeyId = ValidatedKeyId AND ApiRateLimit.WindowStart >= AddSeconds(CurrDateTime(), -ApiRateLimit.WindowSeconds), MaxRecords: 1] → If (GetCurrentWindow.List.Empty) [True] CreateApiRateLimit (WindowStart = CurrDateTime(), RequestCount = 1, MaxRequests = 100, WindowSeconds = 60, ApiKeyId = ValidatedKeyId) [False] If (GetCurrentWindow.List.Current.ApiRateLimit.RequestCount >= GetCurrentWindow.List.Current.ApiRateLimit.MaxRequests) [True] Raise Exception (RateLimitExceeded, User Exception) -- returns HTTP 429 [False] UpdateApiRateLimit (Id = GetCurrentWindow.Id, RequestCount = GetCurrentWindow.RequestCount + 1) → End

When returning a 429 rate limit error, best practice is to include a Retry-After header telling the consumer when they can retry. In the OnAuthentication callback, when raising RateLimitExceeded, you cannot directly add a response header from the exception. Instead, use the OnAfterResponse callback on the same REST API node: In OnAfterResponse (set On After Response → New OnAfterResponse): Start → If (Response.StatusCode = 429) → [True] GetRequestHeader (Name = "X-API-Key") → GetRateLimitWindow (Aggregate for the key) → Assign RetryAfterSeconds = AddSeconds(GetRateLimitWindow.List.Current.ApiRateLimit.WindowStart, GetRateLimitWindow.List.Current.ApiRateLimit.WindowSeconds) → Use SetResponseHeader (HTTPRequestHandler) to add Retry-After header → [False] pass → Assign CustomizedResponse = Response → End Alternatively, include the retry-after information in the exception message so it appears in the JSON error body: "Rate limit exceeded. Retry after " + IntegerToText(SecondsRemaining) + " seconds."

For production APIs, place AWS API Gateway in front of OutSystems: 1. In AWS Console, create a new REST API in API Gateway 2. Create a resource and method matching your OutSystems endpoint (e.g., GET /products/{id}) 3. Set Integration Type to HTTP Proxy 4. Set Endpoint URL to your OutSystems endpoint: https://yourserver.outsystemscloud.com/Module/rest/v1/products/{id} 5. Configure method request to pass the {id} path parameter through 6. Add a Usage Plan: API Gateway → Usage Plans → Create → set Throttle (rate/burst) and Quota (daily limit) 7. Create an API Key in API Gateway and attach it to the Usage Plan 8. Deploy the API to a Stage (dev/prod) OutSystems-side configuration: - Update your OnAuthentication to validate the AWS API Gateway consumer key OR trust that AWS handles authentication and configure OutSystems to accept only requests from the AWS Gateway IP ranges - Consider removing OutSystems-level authentication for gateway traffic to avoid double authentication overhead Environment variable configuration: Store the API Gateway URL as a Site Property for use in documentation and logging.

For on-premises O11 deployments, Kong is a popular open-source gateway: 1. Install Kong (Docker: docker run -d --name kong kong:latest) 2. Configure a Service pointing to your OutSystems server: POST http://localhost:8001/services { "name": "outsystems-api", "url": "https://yourserver/Module/rest/v1" } 3. Add a Route: POST http://localhost:8001/services/outsystems-api/routes { "paths": ["/api/v1"], "strip_path": true } 4. Enable the Rate Limiting plugin: POST http://localhost:8001/services/outsystems-api/plugins { "name": "rate-limiting", "config": { "minute": 100, "hour": 1000, "policy": "local" } } 5. Enable the Key Auth plugin for API key management: { "name": "key-auth", "config": { "key_names": ["X-API-Key"] } } With Kong handling authentication and rate limiting, update your OutSystems OnAuthentication to either pass through (Authentication = None — only safe if Kong and OutSystems are on the same private network) or validate an internal key that Kong injects after its own validation.

ODC differs from O11 in rate limiting: Platform-level limits (ODC, automatic, cannot be modified): - Management APIs (ODC Portal APIs): 100 requests/minute with adaptive throttling - Application REST APIs (your exposed endpoints): No platform-level request throttling — rate limiting is your responsibility - Container scaling: ODC scales containers automatically, so rate limiting is about protecting downstream systems and controlling costs, not protecting OutSystems itself For ODC application APIs: - Use the same OnAuthentication counter pattern from step 2 (works identically in ODC) - Preferred: integrate with AWS API Gateway (OutSystems uses AWS, so low latency) or use Cloudflare Workers in front of the ODC app domain - ODC Portal → App Security → provides vulnerability scanning but not rate limiting ODC adaptive throttling for management APIs returns HTTP 429 with Retry-After header automatically when the 100 req/min limit is exceeded — no configuration needed.