Resolve remaining questions within RPC plans

[seancolsen]

This PR makes changes to our RPC plans document to resolve some of the outstanding questions by proposing answers to them.

Rendered doc

Specifically:

• Timeline is clarified to indicate that we don't intend to transition all REST endpoints to RPC by the beta release.

• rpc-client.md is updated to specify that we will manually maintain TypeScript types and we won't attempt to auto-generate them.

• We'll avoid attempting to transition the data_files endpoint to RPC any time soon.

• We'll use "fixed ids", keeping the scope of unique id values limited to a single HTTP request.

• We'll use the standard verbs: list, get, add, patch, replace, and delete.

• We'll allow arbitrarily deep namespacing.

• I removed questions about response structure and error structure, thinking that we'll basically resolve this as we go by establishing precedent. Perhaps we'll choose to document this later, but I'm not sure.

• I removed the "casing transformation" and "error types" questions because I think the answer is basically "we don't want to spend time on this", including tiding up and properly documenting our decision process. Basically this decision process ocurred within my head and I don't think it's worth the time to capture it.

• I filled in names for all of the RPC functions.

[seancolsen]

@pavish @mathemancer please review to make sure you're on board with the small decisions I'm proposing here.

[seancolsen]

One small comment/question for @mathemancer and @pavish...

This PR has method names which use plural nouns like this:

schemas.add
schemas.delete
schemas.get
schemas.list
schemas.patch

I used plural nouns in the PR because that's how Brent started off in mathesar-foundation/mathesar#3524

However, I have a slight preference for using singular nouns like this:

schema.add
schema.delete
schema.get
schema.list
schema.patch

Would you two be okay with singular nouns?

I'm fine with plural nouns if that's what you two prefer.

[pavish]

@seancolsen Looks good to me!

I have a slight preference towards plural nouns in the function names. I do not have a strong opinion and I'm good with either.

[mathemancer]

Overall, the changes look great. One change I'd suggest adding is to update the documentation of our docstring style from Sphinx to the Google style

[mathemancer]

Is this actually a thing? I.e., is there a UI flow for wholesale replacing an exploration?

[seancolsen]

Yes. When the user clicks the "Save" button on an exploration, we go here and then here. That's a PUT request. This is code that @pavish wrote, I think with Dom's help on the backend. I imagine they both had a good reasons for using PUT instead of PATCH, but I don't understand enough about the inner-workings of the exploration data structures to understand why. In my audit of REST endpoints, this one did stand out to me as the only endpoint where we're using a PUT request.

@pavish if you want to shed any light on your reasoning here, that might be helpful.

[mathemancer]

We're no longer using Sphinx, but rather Google-style docstrings.

[seancolsen]

Fixed in 632e0ce

[mathemancer]

Overall, I'm supportive of the naming scheme you have here. Thanks for going through the details on it!

[seancolsen]

@mathemancer this is ready for re-review.

[mathemancer]

All good from my end.