Hi all,
While working in the HTML Architect, I noticed its HTTP API has grown organically into a mix of styles without a consistent convention. Some endpoints are resource-oriented, others are action/verb-oriented, and the split doesn’t follow a clear rule — so it’s hard to predict what an endpoint looks like or where a new one should go.
Why it matters: as the Architect keeps growing, an inconsistent API surface makes it harder to onboard, to keep error handling and status codes uniform, and to reason about what each endpoint does. A predictable convention would pay off in maintainability.
I don’t think the answer is forcing everything into strict REST — a lot of the operations are genuinely commands (run, transform, validate, wizards, session-style actions) that map more naturally to an RPC style. My hunch is that a deliberate hybrid is the right fit: resource/CRUD-style things as REST, genuine operations as RPC — but only if the boundary follows a clear, documented principle rather than being ad hoc.
Proposal: I’d like to take on a research pass to explore whether the API can be split into REST and RPC in a way that’s actually meaningful and consistent — define the guiding principle for what goes where, sanity-check it against the existing endpoints, and flag the awkward/borderline cases. The outcome would be a short write-up with a recommended convention, before anyone touches code.
Before I dig in — is there any existing convention, prior discussion, or preference on API style I should build on? I want to align with the project’s direction rather than invent something in isolation.
I’m happy to do this investigation and report back with findings and a concrete recommendation. If there’s interest, I can follow up with a proposal we can discuss before any implementation.
Thanks!