mirror of
https://github.com/tiqi-group/pydase.git
synced 2025-06-06 13:30:41 +02:00
adds user guide for restful api
This commit is contained in:
Mose Müller
parent
0e73239d08
commit
6f4fcf52dd
9
docs/user-guide/Interaction.md
Normal file
9
docs/user-guide/Interaction.md
Normal file
@ -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
|
||||
%}
|
||||
|
||||
15
docs/user-guide/RESTful API.md
Normal file
15
docs/user-guide/RESTful API.md
Normal file
@ -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://<hostname>:<port>/api/v1/
|
||||
```
|
||||
|
||||
<swagger-ui src="./openapi.yaml"/>
|
||||
|
||||
## Change Log
|
||||
|
||||
- v0.9.0: Initial release with `get_value`, `update_value`, and `trigger_method` endpoints.
|
||||
256
docs/user-guide/openapi.yaml
Normal file
256
docs/user-guide/openapi.yaml
Normal file
@ -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"
|
||||
Loading…
x
Reference in New Issue
Block a user