From 6f4fcf52dd3416aa21bb07225fc7ad3211093b0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mose=20M=C3=BCller?= Date: Thu, 25 Jul 2024 16:32:21 +0200 Subject: [PATCH] adds user guide for restful api --- docs/user-guide/Interaction.md | 9 ++ docs/user-guide/RESTful API.md | 15 ++ docs/user-guide/openapi.yaml | 256 +++++++++++++++++++++++++++++++++ 3 files changed, 280 insertions(+) create mode 100644 docs/user-guide/Interaction.md create mode 100644 docs/user-guide/RESTful API.md create mode 100644 docs/user-guide/openapi.yaml diff --git a/docs/user-guide/Interaction.md b/docs/user-guide/Interaction.md new file mode 100644 index 0000000..fcd9114 --- /dev/null +++ b/docs/user-guide/Interaction.md @@ -0,0 +1,9 @@ +# Interacting with `pydase` Services + +`pydase` offers multiple ways for users to interact with the services they create, providing flexibility and convenience for different use cases. This section outlines the primary interaction methods available, including RESTful APIs, Python client based on Socket.IO, and the auto-generated frontend. + +{% + include-markdown "./RESTful API.md" + heading-offset=1 +%} + diff --git a/docs/user-guide/RESTful API.md b/docs/user-guide/RESTful API.md new file mode 100644 index 0000000..47939b7 --- /dev/null +++ b/docs/user-guide/RESTful API.md @@ -0,0 +1,15 @@ +# RESTful API + +The `pydase` RESTful API provides access to various functionalities through specific routes. Below are the available endpoints for version 1 (`v1`) of the API, including details on request methods, parameters, and example usage. + +## Base URL + +``` +http://:/api/v1/ +``` + + + +## Change Log + +- v0.9.0: Initial release with `get_value`, `update_value`, and `trigger_method` endpoints. diff --git a/docs/user-guide/openapi.yaml b/docs/user-guide/openapi.yaml new file mode 100644 index 0000000..5073456 --- /dev/null +++ b/docs/user-guide/openapi.yaml @@ -0,0 +1,256 @@ +openapi: 3.1.0 +info: + title: Pydase RESTful API +tags: + - name: /api/v1 + description: Version 1 +paths: + /api/v1/get_value: + get: + tags: + - /api/v1 + summary: Get the value of an existing attribute. + description: Get the value of an existing attribute by full access path. + operationId: getValue + parameters: + - in: query + name: access_path + schema: + type: string + example: device.channel[0].voltage + required: true + description: Full access path of the service attribute. + responses: + '200': + description: Successful Operation + content: + application/json: + schema: + $ref: '#/components/schemas/SerializedAttribute' + examples: + Exists: + summary: Attribute exists + value: + docs: My documentation string. + full_access_path: device.channel[0].voltage + readonly: false + type: float + value: 12.1 + DoesNotExist: + summary: Attribute or does not exist + value: + docs: null + full_access_path: device.channel[0].voltage + readonly: false + type: "None" + value: null + /api/v1/update_value: + put: + tags: + - /api/v1 + summary: Update an existing attribute. + description: Update an existing attribute by full access path. + operationId: updateValue + requestBody: + description: Update an existent attribute in the service + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateValue' + required: true + responses: + '200': + description: Successful Operation + '400': + description: Could not Update Attribute + content: + application/json: + schema: + $ref: '#/components/schemas/SerializedException' + examples: + List: + summary: List out of index + value: + docs: null + full_access_path: "" + name: SerializationPathError + readonly: false + type: Exception + value: "Index '2': list index out of range" + Attribute: + summary: Attribute or does not exist + value: + docs: null + full_access_path: "" + name: SerializationPathError + readonly: false + type: Exception + value: "Key 'invalid_attribute': 'invalid_attribute'." + /api/v1/trigger_method: + put: + tags: + - /api/v1 + summary: Trigger method. + description: Trigger method with by full access path with provided args and kwargs. + operationId: triggerMethod + requestBody: + description: Update an existent attribute in the service + content: + application/json: + schema: + $ref: '#/components/schemas/TriggerMethod' + required: true + responses: + '200': + description: Successful Operation + content: + application/json: + schema: + $ref: '#/components/schemas/SerializedAttribute' + examples: + NoneReturn: + summary: Function returns None + value: + docs: null + full_access_path: "" + readonly: false + type: "NoneType" + value: null + FloatReturn: + summary: Function returns float + value: + docs: null + full_access_path: "" + readonly: false + type: "float" + value: 23.2 +components: + schemas: + UpdateValue: + required: + - access_path + - value + type: object + properties: + access_path: + type: string + example: device.channel[0].voltage + value: + $ref: '#/components/schemas/SerializedValue' + TriggerMethod: + required: + - access_path + type: object + properties: + access_path: + type: string + example: device.channel[0].voltage + args: + type: object + required: + - type + - value + - full_access_path + properties: + full_access_path: + type: string + example: "" + type: + type: string + enum: + - list + value: + type: array + items: + $ref: '#/components/schemas/SerializedValue' + kwargs: + type: object + required: + - type + - value + - full_access_path + properties: + full_access_path: + type: string + example: "" + type: + type: string + enum: + - dict + value: + type: object + additionalProperties: + $ref: '#/components/schemas/SerializedValue' + SerializedValue: + required: + - full_access_path + - type + - value + type: object + properties: + docs: + type: string | null + example: null + full_access_path: + type: string + example: "" + readonly: + type: boolean + example: false + type: + type: string + example: float + value: + type: any + example: 22.0 + SerializedAttribute: + required: + - full_access_path + - type + - value + type: object + properties: + docs: + type: string | null + example: My documentation string. + full_access_path: + type: string + example: device.channel[0].voltage + readonly: + type: boolean + example: false + type: + type: string + example: float + value: + type: any + example: 22.0 + SerializedException: + required: + - full_access_path + - type + - value + type: object + properties: + docs: + type: string | null + example: Raised when the access path does not correspond to a valid attribute. + full_access_path: + type: string + example: "" + name: + type: string + example: SerializationPathError + readonly: + type: boolean + example: false + type: + type: string + example: Exception + value: + type: string + examples: + value: + "Index '2': list index out of range" + some: + "Index '2': list index out of range"