labthings_fastapi.endpoints

Add a FastAPI endpoint without making it an action.

The EndpointDescriptor wraps a function and marks it to be added to the HTTP API at the same time as the properties and actions of the host Thing. This is intended to allow flexibility to implement endpoints that cannot be described in a Thing Description as actions or properties.

It may use any fastapi responses or arguments, as it passes keyword arguments through to the relevant fastapi decorator.

This will most usually be applied as a decorator with arguments, available as @endpoint. See the documentation for that function for more detail.

Attributes

HTTPMethod

Valid HTTP verbs to use with endpoint or EndpointDescriptor.

Functions

endpoint(→ Callable[[Callable], EndpointDescriptor])

Mark a function as a FastAPI endpoint without making it an action.

Module Contents

labthings_fastapi.endpoints.HTTPMethod

Valid HTTP verbs to use with endpoint or EndpointDescriptor.

labthings_fastapi.endpoints.endpoint(method: HTTPMethod, path: str | None = None, **kwargs: Any) → Callable[[Callable], EndpointDescriptor]

Mark a function as a FastAPI endpoint without making it an action.

This decorator will cause a method of a Thing to be directly added to the HTTP API, bypassing the machinery underlying Action and Property affordances. Such endpoints will not be documented in the Thing Description but may be used as the target of links. For example, this could allow a file to be downloaded from the Thing at a known URL, or serve a video stream that wouldn’t be supported as a Blob.

The majority of Thing implementations won’t need this decorator, but it is here to enable flexibility when it’s needed.

This decorator always takes arguments; in particular, method is required. It should be used as:

class DownloadThing(Thing):
    @endpoint("get")
    def plain_text_response(self) -> str:
        return "example string"

This decorator is intended to work very similarly to the fastapi decorators @app.get, @app.post, etc., with two changes:

  1. The path is relative to the host Thing and will default to the name

    of the method.

  2. The method will be called with the host Thing as its first argument,

    i.e. it will be bound to the class as usua.

Parameters:

  • method – The HTTP verb this endpoint responds to.

  • path – The path, relative to the host Thing base URL.

  • **kwargs – Additional keyword arguments are passed to the fastapi.FastAPI.get decorator if method is get, or to the equivalent decorator for other HTTP verbs.

Returns:

When used as intended, the result is an EndpointDescriptor.