rest-server: RFC for v1 job submission schema

[tpatki]

Problem: Our submit API currently accepts whatever field names

JobspecV1.from_command() happens to use (num_tasks, gpus_per_task,
etc.), as we just pass fields through directly. This means our
public API is tied to flux-core's internal Python signature, not a
schema we actually chose -- and it's not discoverable (e.g. num_gpus
-> 400, gpus_per_task -> 200, with no way to know which without
reading flux-core's source).

Approach (based on discussion with @garlick in PR #7):

Leave it as-is for now for early testing with friendly users, since it works and is
minimal. Before real users depend on it, design a proper v1 schema
with a fixed, documented set of fields we control -- ideally with
input from early adopters -- so we can keep it stable even if
flux-core's internals change later. If the main use case is simple
batch jobs, this field set may end up quite small.
As a result, the interface may change before the first tagged
release.

Also worth deciding as part of this RFC: whether "basic" submit
should stay built on JobspecV1.from_command(), or move to
from_submit() instead. from_command()'s own docstring points at
from_submit() as "a more full-featured alternative... supports most
options offered by the flux-submit CLI utility." If the goal is for
the REST API to eventually mirror flux submit at the CLI, from_submit()
may be the better foundation.
This also connects to the planned command-line
submit endpoint from issue #6 , which was already slated to use
from_submit() with the /api/v1/jobs/submit-cli.

[garlick]

Although we may not have machinery built for OpenAPI from the beginning, using OpenAPI as a specification language (for example in an RFC) as recommended here[1] seems like a good idea!

[1] https://opensource.zalando.com/restful-api-guidelines/#general-guidelines

[garlick]

FWIW I asked claude to generate an example openapi spec for this project: openapi-v1-draft.yaml

just to illustrate what it would look like.