Cannot read api-prefix from a thing or server

[julianstirling]

There is currently no way to get the internal path of a thing without the API prefix. Not to get the api_prefix from the server from public attributes.

From within a Thing

The OpenFlexure server saves data from each thing in a directory <data_dir>/self.path. As we add an API path of /api/v3 this means that we end up saving scans at <data_dir>/api/v3/smart_scan not <data_dir>/smart_scan.

This is fairly easily solved by using self.name rather than self.path, but this isn't future proof against in future being able to have "sub-Things" and nested paths.

It would be nice to have a way to either:

• read the api path from the ThingServerInterface, or
• have something like self.path be /smart_scan/ and self.full_path be /api/v3/smart_scan/ [Breaking change if we release this RC as 0.2.0]
• possibly self.path be /api/v3/smart_scan/ and self.internal_path be /smart_scan/

From a function that has an instance of a ThingServer

When starting the server, we need to add API routes. To mount the data directory within the API path we need to read the prefix. We can do this from server._api_prefix. It would be ideal to have this read-only property part of the public API for the server class.

Details

• Version: 0.2.0rc1

[rwb27]

Is there a reason you want to use path rather than name? Thing.name is the string I'd intend to use as an identifier. I realise that may not be super obvious, and indeed it may not yet be consistently used in the code. A Thing's settings folder should be /top/level/settings/{name}/settings.json or whatever. My hope is that path can be eliminated as a variable in the future in favour of url_for.

Currently I think path is defined to be {api_prefix}/{name}/ give or take a slash or two.

[julianstirling]

My understanding was that there would be plans in the future for things to have sub things. So a system with say 2 cameras could have background detectors which are specific to that camera, which made me think there would be nesting and they would have paths like and I assumed settings of

• settings/camera1/method_a_bg_detect/settings.json
• settings/camera2/method_a_bg_detect/settings.json

If this isn't a planned feature and names will always be unique then that is fine.

It would still be good for ThingServer not to have _api_prefix as private, as any code that has access to the Server instance when setting up may need to know this for things like setting other endpoints

[rwb27]

At the moment, name must be unique, as it's used as the key to the dictionary of Things. I like the concept of sub-Things but I think it may be a while before that gets implemented. I was also anticipating we could potentially implement them by allowing dots in a name in specific circumstances, so in your example above Thing.name might end up being camera1.background_detectors.a (assuming camera1.background_detectors is a Thing Slot). There's certainly a discussion to be had about dots vs slashes. My gut feeling is that dots are safer, and if we want to turn them into slashes (e.g. in URLs) we can do that when we need to.

Moving the codebase towards using url_for properly will necessitate unique endpoint names. The obvious (to me) way to do this is naming endpoints {thing_name}.{attr} because that's already required to be unique. Allowing sub-Things to appear as though they sit within a Thing Slot feels like the neatest way to fit them into this hierarchy to me.

All of this is for a future discussion. I think for now it should be safe to conclude that Thing.name is a sensible unique identifier to use, and ought to remain so.

[rwb27]

As for allowing access to the api prefix, I feel like it's reasonable for stuff that is customising the server, but in principle a Thing ought not to be using it much if at all. Thing endpoints should be relative to/appear as sub-paths of the Thing's base URL, much confusion is likely to result if that isn't adhered to.

If there are examples that require us to deviate from that, it would be good to list them and figure out the best way to implement them.

[julianstirling]

Currently when starting up the server any endpoints or mount points that are not connected to a thing need to be created directly on the server. Such as mounting a data directory within the API so that data can be loaded in the UI where the blob mechanism doesn't work well (for example the OpenFlexure Microscope needs this for openseadragon).

I think in general there is a philosophy in LabThings development that everything is disallowed/secret unless we provide a really fight for it not to be. It makes the framework feel very paternalistic as it is trying to ensure people can only write code in the way that is considered best. The problems with highly opinionated frameworks like LabThings is that as a user of the framework it can me very difficult and constraining to use for any use case that isn't actively considered when writing. This is regular pain point from developing the project the framework is specifically for.

It is one thing to make a property for api_prefix that has a docstring that explains that it is not a reliable way to create URLs, but it is another thing all together to refuse to share the information because we can't need it. This leads to us trying to fight the framework.

[rwb27]

I should have added to my last message that I've no issue making ThingServer.api_prefix a public property, that seems fine and to be honest I'm not entirely sure why I didn't make it public when I added it. Clearly code that customises the server should be able to access that. I have implemented that, and a minor docs improvement, in #339.

I have typed a few replies to your more general points about how LabThings is designed but I think we might do well to have that chat in a different medium first.

[julianstirling]

Thanks Richard. Sorry my last message was overly grumpy, I should make a note to never respond before my morning coffee.

I think it is worth a discussion, probably best done on a call. I think there is a tension between making a framework that makes it easy to do the right thing and harder/impossible to do the wrong thing vs a framework that is flexible to use cases that were not considered. I feel the balance probably needs discussing it will always b hard to get perfect.

[rwb27]

No worries, I understand the frustration of fighting a framework from the odd things I try to do with FastAPI and pydantic... We'll chat soon and I'm sure we'll figure it out.