[COMPLETE] An API for Open Brush

[andybak]

I've started a feature branch for a proposed API: https://github.com/ixxyxR/open-brush/tree/features/http-api

I'd like to note down some stuff here so people can chime in with their own thoughts.

Open Brush already listens for incoming http requests on port 40074 so it makes sense to reuse that.

I want the API to be simple enough that it can be used directly from the browser address bar without needing to write any javascript.

You should be able to just paste in URLs and see the results in your headset (or on your monitor - another goal is for this to be useful without VR)

It's also quite nice to be able to send multiple commands at once so I've gone with using query parameters as key value pairs.

Commands requiring more than one word to be clear use . as a seperator:

http://localhost:40074/api/v1?brush.color=green

API commands that take multiple arguments are handled in ad hoc ways - the convention being a comma separated list:

http://localhost:40074/api/v1?camera.lookat=0,2,1.5

There's a simple "turtle graphics" system and you can chain commands in a single url:

http://localhost:40074/api/v1?brush.turn=45&brush.move=1&brush.draw=1.5

It accepts POST as well as GET:

<form method="POST" action="http://localhost:40074/api/v1">
    <label>Turn: <input name="brush.turn" value="45"></label>
    <label>Move: <input name="brush.move" value="1.5"></label>
    <label>Draw: <input name="brush.draw" value="2"></label>
    <button type="submit">Go</button>
</form>

I'll also accept some form of JSON. Maybe something like:

[
    {'command': 'brush.color', 'params': ['red']},
    {'command': 'brush.moveto', 'params': [1,2,3]},
    {'command': 'draw.text', 'params': ['hello']}
]

[andybak]

Currently the API is asynchonous. You fire off a command and it gets queued. One command is popped off the queue at a time and executed (maximum one command per frame).

This is nice and non-blocking but it means commands can't return values.

I'd quite like the API to allow interogating the current state of the sketch so return values would be handy.

I'm considering as a solution - every api call returns a handle (a guid). You can issue another request asking for the status of a command.

This will either return "pending" or it will return some JSON with the return values. These commands alone would return synchonously.

[andybak]

This is the part I'm uncertain about.

(I went with this design because that's how the existing "API" was set up - API in this case is just a single endpoint - to load a scene from disk)

An alternative is to make all API calls blocking and push the job of managing promises or whatnot on to the client.

But this raises the bar somewhat for people wanting to write simple javascript to automate things. Or does it?

[billyquith]

What do you intend to use the API for? I think that should be the starting point, not the implementation details. Create a list of examples of things you would like to do with the API, then work out the functionality required, then work out the implementation details. This will tell you how granular your HTTP API needs to be.

[billyquith]

For instance telnet might be a better approach for what you want. Then you can just type stuff in interactively.

https://github.com/UngarMax/TelnetServer/blob/master/Server.cs

[mikeage]

I love this idea.

Regarding the API itself... it's not particularly RESTful. Is invocation from a browser (which requires GETs) a key requirement? If not, I'd prefer something like POST http://localhost:40074/api/v1/brush/draw or similar, but that means curl or postman or a dedicated GUI page.

What about GETting the current drawing or camera (I think those would be the two things that would be queried)? Is that a meaningful operation?

General question that I don't know -- how similar is the current save file format to these type of APIs? Is it possible or desirable to unify them?

[andybak]

how similar is the current save file format to these type of APIs? Is it possible or desirable to unify them?

Very different. The current save format just contains stroke data and references to external assets such as Blocks models hosted on Poly.

[andybak]

it's not particularly RESTful.

It wasn't really intended to be. I was aiming more for a kind of "RPC over HTTP" style. I'm not sure how much value REST (whatever one's interpretation of that rather nebulous concept is) would bring to this.

Is invocation from a browser (which requires GETs) a key requirement?

No but it does bring benefits. And if I were to abandon it, I'd want to hear what the downsides are.

If we also want to accept simple formencoded POSTs then they are also basically a list of key-value pairs. So supporting GET doesn't really apply any additional restrictions.

And it makes it really simple to use for people.

1. If we don't accept GET then we've raised the bar for participation to "I know how HTML forms work"
2. If we also don't accept formencoded (presumably in favour of JSON payload) then we've raised the bar again to "I know enough javascript to constuct json and use xhr.request"

I think this is a shame and limits the potential audience for the API.

(EDIT - actually point 2 is a bit confused. I realised what you were probably arguing for after I wrote this. See below)

I'd prefer something like POST http://localhost:40074/api/v1/brush/draw or similar, but that means curl or postman or a dedicated GUI page.

Aren't you conflating two things? Once you've decided you like http://localhost:40074/api/v1/brush/draw then does it matter whether the parameters are in the query string or the request body? One isn't any more or less RESTful than the other. So we could use your style and not need curl or postman.

The real distinction we seem to be discussing is whether the command (as distinct from the parameters) should be in the path vs the "key" of each key value pair.

The advantage of my approach is that a single request can carry multiple commands. And again - this means that simple URLs and simple HTML forms can do more interesting stuff without needing javascript.

[mikeage]

Can you elaborate a bit more on that audience, though? Is this a way to demonstrate something? Write scripts? Share drawings? Collaborate?

I agree about SOAP and RPC, just saying that it might be a simpler way to arrange it. Does it really matter? No. :-)

[andybak]

Can you elaborate a bit more on that audience, though?

Is "I don't know" a valid answer? I'm rather hoping that the audience surprises me. I would like people I never expected to do things I didn't predict.

[andybak]

I think the key thing here is whether a single request can contain mulitple commands. That's the real advantage of the key-value approach. Everything else is fairly trivial.

How much of an advantage is this? My initial post above shows some nice uses of this.

For example

http://localhost:40074/api/v1?brush.turn=45&brush.move=1&brush.draw=1.5

is a cute demo. It draws a line, changes the colour and turns. You do it 8 times and you have a multicoloured octagon.

And the HTML form example shows a simple way someone with a basic understanding of HTML could build something that took complex actions with a single "submit".

Is this a valid use-case? I kinda like it but maybe it's too niche.

[mikeage]

Sorry, I'd never written back here. Seeing some of the stuff you did, I'm definitely seeing a lot of value in both "snippets" as well as repetitive scenes, which are both excellent use cases, even if it turns out that there are no others (although I suspect there will be!)

[andybak]

Thanks. I'm still bikeshedding about the specific wording of the commands. I've been going backwards and forwards with several variants of brush.color.rgb=1,2,3 vs brush.rgb=1,2,3 vs brush.color=1,2,3 (but then what about hsv...)

I think I might just have to put something out there and see if I can get feedback that way.