[RFD]: REST API standards

[alexlovelltroy]

Decision Goal

Based on discussion(s), we should create a single API Development Standards document in the community repo and a set of reusable tests that verify API compliance

Category

Code Quality

Stakeholders / Affected Areas

Developers

Decision Needed By

No response

Problem Statement

OpenCHAMI microservices expose REST APIs which can be consumed by clients and other services. While REST itself describes the way resources are represented and modified over http using verbs, it intentionally doesn't prescribe associated API standards and behaviors.

Within OpenCHAMI, we seek to establish a set of conventions and tests to validate those conventions which make client development easier and provide intuitive interfaces.

Proposed Solution

I propose we create API implementation standards for APIs controlled by OpenCHAMI. We should store these standards in the community repository. We should subsequently create tests that validate services are following our standard conventions and flag variances as BUGs in the appropriate repositories.

For discussion and possible inclusion:

• [RFD] Contract definition language #88
• [RFD] Authentication #87
• [RFD] Bulk Operation: Bulk PATCH #86
• [RFD] Bulk Operations: Bulk path #84
• [RFD] Asynchronous Operations #83
• [RFD] Pagination #82
• [RFD] Results Filtering #81
• [RFD] Standard Query Parameters #80
• [RFD] API Versioning #78
• [RFD] API Tagging #79
• [RFD] JWTs for microservice authentication #11

Alternatives Considered

No response

Other Considerations

No response

Related Docs / PRs

No response

[rainest]

Easy bit:

We'd probably need to separate standards for all APIs versus CRUD APIs. AFAIK most of the issues where that matters state as much, but it's worth restating: you cannot paginate the readiness endpoint, but it is part of a version contract.

---

Less easy bit:

I don't think we can readily commit to these without something along the lines of #88 first.

AFAIK current API handlers are hand-written (e.g. https://github.com/OpenCHAMI/power-control/blob/main/internal/api/power-status.go or https://github.com/OpenCHAMI/smd/blob/main/internal/hmsds/hmsds-api.go) and don't follow a common design or standard, sometimes in significant ways (in the prior two examples, SMD's much more closely coupled to its storage engine).

Manually writing and maintaining generic CRUD endpoints and schemas for resources is tedious and error-prone. We should care mostly about writing structs, and have tooling automatically update API code and schemas on our behalf. API implementation generation is maybe beyond #88, but I think it's something we'd benefit from, and tooling I can find generally provides both.

IDK if anyone else has more familiarity with HTTP API generators--I do not, I come from the simple Kubernetes world of "use client-go and kubebuilder, they'll take care of everything for you". I can at least offer the time-honored "use reddit as a community survey", which lists a few. Excluding the more GraphQL or gRPC-focused ones:

• The aforementioned OpenAPI generator.
• Huma, which can target Chi or net/http, looks like it can help with OpenAPI manifest generation from structs, and supports several JSON patch standards.
• Goa, which uses a bespoke DSL (but generates OpenAPI), and probably targets Chi (it doesn't say in the readme, but it does require Chi).
• Fuego, which indirectly targets Chi and generates OpenAPI.

Offhand, I don't see obvious out of box support for the proposed API features, and I don't know how easy it'd be to add them--that'd require more research.

I'm reluctant to commit to the proposed without a proof-of-concept for how we'd handle them in code--we need to understand how much development and maintenance burden we're taking on before committing to them.

If this would require maintenance of a generator fork, or worse, manual work for each type, we'd need a much stronger rationale for blanket requirements, and should consider implementing it per-resource as needed.