PUT /api/v1/meta/:type/:name is hard to discover — add a POST convenience alias

[akarma-synetal]

Problem

The save endpoint for metadata items is registered as PUT /api/v1/meta/:type/:name in packages/rest/src/rest-server.ts. This is correct REST semantics, but creates discoverability friction:

1. Only PUT is accepted. Many API clients and tools default to POST (Postman defaults, fetch with body, curl -d). Sending a POST to the correct path returns a generic 404 with no hint that PUT is the expected method.

2. No helpful error when :name is missing. A request like POST /api/v1/meta/view/?mode=draft (trailing slash, missing name segment) doesn't match /:type/:name and returns {"error":"Not found"}. Callers have no way to distinguish "route doesn't exist" from "URL is malformed."

Proposed solution

A. Register a POST alias in registerMetadataEndpoints() (at packages/rest/src/rest-server.ts ~line 2746) that delegates to the same handler as the PUT route. This is safe because:

• Sub-routes (/publish, /rollback) are already registered as more-specific POST paths that match first
• The handler uses ?mode=draft query param (not HTTP method) to distinguish draft saves

B. Optionally register a descriptive error handler on /:type alone so that incomplete URLs return a useful message instead of a generic 404.

Expected outcome

# Before
$ curl -X POST http://localhost:8080/api/v1/meta/view/my_view?mode=draft -d '{}'
{"error":"Not found"}

# After
$ curl -X POST http://localhost:8080/api/v1/meta/view/my_view?mode=draft -d '{}'
{"name":"my_view", ...}   # works via POST alias

Where

packages/rest/src/rest-server.ts — registerMetadataEndpoints(), PUT handler around line 2746

[os-zhuang]

Thanks for the detailed writeup — the diagnosis is spot on, and I've opened #2687 to address it. I went a slightly different direction than the proposed POST alias, so here's the reasoning.

Root cause is framework-wide, not metadata-specific. The bare {"error":"Not found"} doesn't come from the metadata route — it's the global notFound handler in plugin-hono-server. Hono routes a method mismatch to the same sink as a genuinely missing path, so every non-GET route (translations save, PATCH /data/:object/:id, DELETE /meta/:type/:name, …) has this exact discoverability gap, not just PUT /meta/:type/:name.

Why not the POST→PUT alias (solution A). It works, but it has two downsides: it blurs REST semantics (PUT is idempotent, POST isn't) and it puts two entries in the OpenAPI surface for one operation. More importantly, it only patches the metadata endpoint — the underlying "wrong method returns an unhelpful 404" problem stays everywhere else.

What #2687 does instead. It fixes the root cause: when a request matches a registered path under a different method, the server now returns a proper 405 Method Not Allowed with an accurate Allow header — for every endpoint. So your example becomes self-explanatory:

$ curl -i -X POST /api/v1/meta/view/my_view
HTTP/1.1 405 Method Not Allowed
Allow: DELETE, GET, HEAD, PUT
{"error":"Method Not Allowed","code":"METHOD_NOT_ALLOWED",
 "message":"POST is not supported for /api/v1/meta/view/my_view. Allowed: DELETE, GET, HEAD, PUT.",
 "allowed":["DELETE","GET","HEAD","PUT"], ...}

The client immediately sees that PUT is the expected verb, instead of guessing whether the route exists at all. Paths that match no route at all stay a genuine 404.

On your second point (missing :name, e.g. POST /meta/view/?mode=draft). That URL doesn't match any registered pattern — the :name segment is empty — so it's genuinely "route doesn't exist," not a method mismatch, and correctly stays a 404. If you'd find a dedicated "name segment is required" hint on /meta/:type valuable, I'm happy to add it as a follow-up; it needs to be method-scoped so it doesn't shadow the existing GET /meta/:type list route.

Let me know if you'd actually prefer POST to work (accept-the-request) rather than be guided to PUT — that's a maintainer call and easy to layer on top, but the 405 felt like the more principled default.

---

Generated by Claude Code