Feature Request: Enhanced API Documentation, Usage Examples, and Developer “Recipes”

[tyronechrisharris]

Summary
We’re currently preparing test cases and integration plans for OSCAS and need better support around the REST API exposed by this project. While we’ve confirmed it uses an OpenAPI-based interface, deeper documentation and practical examples are needed to ensure successful use by downstream systems, test harnesses, and developers.

1. Practical API Usage Examples ("Recipes")

• Code snippets or workflow samples for common operations such as:

  • Listing RPMs and sensor nodes
  • Creating lanes or components
  • Pulling occupancy and alarm data
  • Interfacing with EML feedback

• Suggested formats: cURL, Python (requests), JavaScript (fetch), etc.

2. Expanded OpenAPI Documentation

• A browsable or downloadable OpenAPI spec (e.g., Swagger JSON/YAML)

• Clarification on:

  • Authentication method(s)
  • Required headers or parameters
  • Output structures for common endpoints
  • Add a new /docs/api.md or examples/ folder directly in the repo for future maintainability.

3. Workflow Guides

• Step-by-step walkthroughs for scenarios such as:

  • Connecting and authenticating
  • Querying live sensor streams
  • Handling adjudication logic
  • Simulating or injecting alarms via API

4. Supported/Planned Capabilities

• Indicate what parts of the API are considered:

  • Stable and production-ready
  • In development or planned (e.g., streaming N42 input/output)
  • Deprecated or unsupported

---

Rationale

Providing these improvements would:

• Reduce time to adoption for test teams and new developers
• Help automate large-scale testing (e.g., 50-lane simulations)
• Clarify integration boundaries for systems like the sensor modules, EML, and the web viewer