Separate obs-websocket API from the Rust API

[dnaka91]

One thing that always bothered me with the upcoming v5 of obs-websocket, is the new principle they used for request and field names. The current v4 had a rather inconsistent naming scheme, so that definitely improved. But what I don't like about the new design, is the extremely strong repetition of things inside the names.

Examples in obs-websocket

Simple sample

A simple example would be the SetCurrentSceneCollection command (several fields omitted for simplicity):

{
  "requestType": "SetCurrentSceneCollection",
  "requestData": {
    "sceneCollectionName": "something"
  }
}

I'd argue the command name already gives enough context to understand that the data contains information about scene collections, so sceneCollectionName could simply be named name.

Extreme-ish example

The CreateInput command is a more complex sample, where lots of repetition happens:

{
  "requestType": "CreateInput",
  "requestData": {
    "sceneName": "scene1",
    "inputName": "input1",
    "inputKind": "browser_source",
    "inputSettings": {},
    "sceneItemEnabled": true
  }
}

Here, the input* is repeated over and over in the field names, and the sceneItem* prefix doesn't really add any value either (all we care about is whether it should be enabled, right?).

This could probably be simplified, while still keeping some extra context, by moving some features in a JSON object like "input": { ... } within the requestData.

But that solution isn't possible from the Rust API side without lots of serde mangling and likely custom serializer logic.

Proposal

My current idea is to use the rename feature of serde to reduce the amount of repetition in the Rust structures and adjust function names as well. That allows us to have a simpler API when using the obws crate, but still maintain the original names when talking to obs-websocket.

Rust API comparison

The first sample mentioned above, wouldn't see any outside changes on the API level, so let's focus on the second sample:

client.inputs()
    .create_input(CreateInput {
        scene_name: "scene1",
        input_name: "input1",
        input_kind: "browser_source",
        input_settings: None,
        scene_item_enabled: Some(true),
    })
    .await?;

By adjusting function and field names we can get something way shorter, and still don't lose context (in my opinion), due to calling inputs(). So we know we talk about inputs here.

client.inputs()
    .create(CreateInput {
        scene: "scene1",
        input: "input1",
        kind: "browser_source",
        settings: None,
        enabled: Some(true),
    })
    .await?;

We can shorten scene_name and input_name to just scene and input, as they're mostly identified by their name, throughout the whole API. All following fields relate to creating the input, so it should be clear enough and allow us to use the prefix. As discussed before, it doesn't really give value to know that enabled is related to the created scene item, so we can remove that too.

If there is some unclarity, we still have rustdoc to check the details of each field.

Function renaming

Another quick sample I want to show, is how we can reduce repetition in simpler API calls:

client.scenes().get_scene_list().await?;

This can (in my opinion) be reduced to:

client.scenes().list().await?;

My reasoning here is, that

1. We already know we manage scenes, as we call scenes() so we don't need it in the following function call again. Reducing to get_list().
2. The name get_list() is still kind of double, similar to a command in plain English. We can say get me the list of scenes, or we can be shorter and say list the scenes. Therefore, just list() would do.

Current status

I prepared these changes for most of the APIs, although some naming can be further improved, to be a bit more consistent. Current implementation lives here: https://github.com/dnaka91/obws/tree/naming-redesign.

Also, I'm considering to maybe move the actual request structures into (Rust) sub-modules, to be able to shorten the name further. Like turning requests::CreateInput into requests::inputs::Create.

Not quite sure how much of a good idea that is. It makes the names shorter, but creates many duplicate struct names, so it's likely more bothersome to import.

Downsides

Now I've talked a lot about my opinion about the obs-websocket namings, and how I believe it could be done better. Let's get to the downsides of this new approach.

I don't think here is too much of a negative point, most APIs just become simpler and more readable. Except one: mapping to the obs-websocket docs.

When seeing obws by itself, it has its own docs thanks to rustdoc and should be mostly clear and intuitive to use.

But when people take the other approach and look at obs-websocket docs first, then look for the same commands in obws, they'll likely get confused to where the commands are. Pretty much none of the commands can be directly found by the same name, after this change is done.

I think most of this can be circumvented by putting links into the function docs and module/struct docs to reference back to the original command name in obs-websocket docs.

Final words

This is a pretty long read, so congratulations and thanks for taking the time to read through it.

Before I take this rather big API change, I'm asking all the current users of this crate to tell me what they think. That is, if you happen to find this discussion on GitHub.

[dnaka91]

No response so far, and I like the API redesign more and more, the more I adjust it. So I'll go ahead with this.