dohertj2/scadalink-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refine Inbound API: HTTP contract, extended types, logging, rate limiting

Browse Source 
Define POST /api/{methodName} URL structure with X-API-Key header. Flat JSON
request/response with no envelope wrapper. Add extended type system (Object, List)
for complex API parameters and return values, applied to both Inbound API and
External System Gateway method definitions. Only failures logged; no rate limiting
in this controlled industrial environment.
This commit is contained in:
Joseph Doherty
2026-03-16 08:26:04 -04:00
parent cbc78465e0
commit cd03b77913
3 changed files with 106 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
docs/plans/2026-03-16-inbound-api-refinement-design.md Normal file
View File

@@ -0,0 +1,48 @@
# Inbound API Refinement — Design
**Date**: 2026-03-16
**Component**: Inbound API (`Component-InboundAPI.md`)
**Status**: Approved
## Problem
The Inbound API doc had good coverage of authentication, method definitions, and script capabilities, but lacked a concrete HTTP contract (URL structure, request/response format, API key header), type system for complex data, rate limiting decision, and call logging policy.
## Decisions
### URL Structure
- **`POST /api/{methodName}`** for all calls. Uniform POST — these are RPC-style script invocations, not RESTful resources.
### Request/Response Format
- **Flat JSON, no envelope**. Request parameters as top-level fields. Response is the return value on success (200) or an error object on failure (4xx/5xx). HTTP status codes distinguish success from failure.
### API Key Header
- **`X-API-Key` header**. Explicit, unambiguous, no confusion with OAuth/Bearer patterns.
### Extended Type System
- API method parameters and return values support **Object** and **List** types in addition to Boolean, Integer, Float, String.
- Enables complex nested structures (objects with properties and lists of sub-objects).
- Template attributes retain the simpler four-type system. Extended types apply to Inbound API and External System Gateway method definitions.
### Rate Limiting
- **No rate limiting**. Private API, controlled environment, known callers. Misbehaving callers handled operationally (disable API key). YAGNI.
### API Call Logging
- **Only failures logged.** Successful calls not logged — audit log is for configuration changes, not operational traffic.
## Affected Documents
| Document | Change |
|----------|--------|
| `Component-InboundAPI.md` | Added HTTP Contract section (URL structure, API key header, request/response format, extended type system). Added API Call Logging section. Updated Authentication Details to be definitive about X-API-Key header. |
| `Component-ExternalSystemGateway.md` | Updated method definition parameter/return types to note extended type system support. |
## Alternatives Considered
- **RESTful HTTP method mapping**: Rejected — script invocations are RPC, not CRUD. Forcing GET/PUT/DELETE adds complexity with no benefit.
- **Envelope response format**: Rejected — HTTP status codes already distinguish success/failure. Envelope wrapper is redundant.
- **`Authorization: Bearer` header**: Rejected — implies OAuth/token auth, confusing for API key callers.
- **Per-key rate limiting**: Rejected — controlled industrial environment with known callers. Operational handling (disable key) is sufficient.
- **Log all API calls**: Rejected — would flood the audit log with operational traffic, especially from polling integrations.
- **Keep simple four-type system for API**: Rejected — external systems need to send/receive complex nested data structures. JSON string parsing in scripts is error-prone.
- **Configurable per-method logging**: Rejected — adds configuration complexity for a feature not currently needed.