[Bluenix2]

I am starting this pull request as a draft so that there's no conflicts between work. Resolves #115.

So I've thought about these a bit more, and it would probably be better to do the following..

• GET /canvas/ Get the size; this should be the first one the user tries, that's why it's the simplest
• GET /canvas/pixels Get all pixels
• GET /canvas/pixels?x=0&y=0 Get a specific pixel
• PUT Set a specific pixel, unsure which one is best
  • /canvas/pixels x, y and rgb is in the body
  • /canvas/pixels?x=0&y=0 only rgb in the body, but conforms better to how you get a pixel

The biggest issue with this second proposal is that now we have a "conflict" of GET /canvas/pixels and GET/canvas/pixels?x=0&y=0. We cannot have 2 documentation entries to outline this (if we use one that automatically generates documentation from the openapi spec).

Query string parameters must not be included in paths. They should be defined as query parameters instead.
This also means that it is impossible to have multiple paths that differ only in query string, such as:

GET /users?firstName=value&lastName=value
GET /users?role=value

This is because Swagger considers a unique operation as a combination of a path and the HTTP method, and additional parameters do not make the operation unique.

Of course it's not impossible, we can have one shared function. But this means we need to merge get_pixel and pixels doc-string. Leading to more confusion than UX we get.

That makes the first proposal conflict free, that said there may be improvements to be made?

• GET /canvas/size
• GET /canvas/
• GET /canvas/pixels?x=0&y=0
• PUT
  • /canvas/pixels
  • /canvas/pixels?x=0&y=0

[jb3]

Feedback on endpoints:

• Size should explicitly be in the endpoint, so something like GET /canvas/size.
• Fetching an individual pixel should not use pixels plural imo, I'd rather keep it as GET /canvas/pixel?x=1&y=1 or put it in the URL parameters like GET /canvas/pixels/1/2 and document the order.
• I don't like PUT with URL parameter and a body, it doesn't make sense. The document being created should be complete in the body, not partials in two different places.

(Personal thoughts, would like to hear from others)

[Bluenix2]

• Fetching an individual pixel should not use pixels plural imo, I'd rather keep it as GET /canvas/pixel?x=1&y=1 or put it in the URL parameters like GET /canvas/pixels/1/2 and document the order.

Ah, interesting. The way I see it is that we're making a GET request to get the pixels, but we're using query parameters to narrow it down to one. That said, yes using GET /canvas/pixel?x=0&y=0 and GET /canvas/pixelS (plural) would remove that conflict I was talking about.

I don't like PUT with URL parameter and a body, it doesn't make sense. The document being created should be complete in the body, not partials in two different places.

Yeah the former would be better as PUT /canvas/pixel (singular).

[Bluenix2]

While this is being done, should moderation endpoints also get similar changes?

[Bluenix2]

I have now done some basic testing and squashed the commits so that this can be rebased.