Pascal
a0ff5cdebb
- [add] added existing data folder to prevent docker creating one as root - [mod] docker-compose.yml now uses $EUID as default user and group id
386 lines
11 KiB
YAML
386 lines
11 KiB
YAML
openapi: "3.0.0"
|
|
info:
|
|
description: "Simple dynDNS via Rest-API.
|
|
|
|
|
|
The demo database will reset every **60** minutes. A maximum of 250 clients can exist in the demo database.
|
|
|
|
The following default clients and api keys can be used:
|
|
|
|
| client name | api key |
|
|
|
|
|--------------|------------------------------------------------------------------------------------------|
|
|
|
|
| admin | `zW3If4s5.41a7c846.23b142e6451df545d5034ca8f6050b80ff3e9689f20d5e45d72d160fa7e1cf32` |
|
|
|
|
| read_client | `zW3If4s5.28aef5cb.d502cb94ba0802c6363f95ecb3a70de7e2e4b889779e435b7c033f2c72ed4f20` |
|
|
|
|
| write_client | `zW3If4s5.3d6129cc.48d41d2a28b16a9a274d3f407026aee2b82cddbb3c11a5496ffe329c78e5d54b` |
|
|
|
|
In `demo-mode` it is not possible to call `POST /admin/client`, `PUT /admin/client` or `DELETE /admin/clients/{client_name}` for any of the above default clients. Any newly created client can be freely modified.
|
|
|
|
|
|
***Note**: the X-API-Key value entered when using Authorize takes precedence over values entered in the X-API-Key parameters field.
|
|
|
|
Since the X-API-Key parameter field is flagged as required a simple space (or any other character) will still be needed for executing the request here.*
|
|
"
|
|
version: "1.0"
|
|
title: "rynDNS"
|
|
|
|
servers:
|
|
- url: "https://demo.api.pdev.dev/rynDNS"
|
|
description: ""
|
|
|
|
security:
|
|
- api_key: []
|
|
|
|
paths:
|
|
/admin/client:
|
|
post:
|
|
tags:
|
|
- "admin"
|
|
summary: "Create or update a client and retrieve a new API key"
|
|
description: ""
|
|
operationId: "create_client"
|
|
parameters:
|
|
- $ref: "#/components/parameters/api_key"
|
|
requestBody:
|
|
description: "An existing clients properties wil only be updated if the parameter is present."
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/client"
|
|
responses:
|
|
"200":
|
|
description: "Client updated"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/admin_client_api_key"
|
|
"201":
|
|
description: "Client created"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/admin_client_api_key"
|
|
"401":
|
|
$ref: "#/components/responses/unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/forbidden"
|
|
"405":
|
|
description: "Invalid input"
|
|
"406":
|
|
description: "Not Acceptable - Can not remove last admin account permissions"
|
|
"429":
|
|
description: "Too many clients - Maximum client count reached"
|
|
put:
|
|
tags:
|
|
- "admin"
|
|
summary: "Update an existing client"
|
|
description: ""
|
|
operationId: "update_client"
|
|
parameters:
|
|
- $ref: "#/components/parameters/api_key"
|
|
requestBody:
|
|
description: "An existing clients properties wil only be updated if the parameter is present."
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/client"
|
|
responses:
|
|
"200":
|
|
description: "Client updated"
|
|
"401":
|
|
$ref: "#/components/responses/unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/not_found"
|
|
"405":
|
|
description: "Invalid input"
|
|
"406":
|
|
description: "Not Acceptable - Can not remove last admin account permissions"
|
|
/admin/clients:
|
|
get:
|
|
tags:
|
|
- "admin"
|
|
summary: "Retrieve all clients information"
|
|
description: ""
|
|
operationId: "get_all_client"
|
|
parameters:
|
|
- $ref: "#/components/parameters/api_key"
|
|
responses:
|
|
"200":
|
|
description: "OK"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/admin_client_info_array"
|
|
"401":
|
|
$ref: "#/components/responses/unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/forbidden"
|
|
/admin/clients/{client_name}:
|
|
parameters:
|
|
- $ref: "#/components/parameters/api_key"
|
|
- $ref: "#/components/parameters/client_name"
|
|
get:
|
|
tags:
|
|
- "admin"
|
|
summary: "Retrieve client information"
|
|
description: ""
|
|
operationId: "get_client"
|
|
responses:
|
|
"200":
|
|
description: "OK"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/admin_client_info"
|
|
"401":
|
|
$ref: "#/components/responses/unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/not_found"
|
|
delete:
|
|
tags:
|
|
- "admin"
|
|
summary: "Delete an existing client"
|
|
description: ""
|
|
operationId: "delete_client"
|
|
responses:
|
|
"200":
|
|
description: "Client deleted"
|
|
"401":
|
|
$ref: "#/components/responses/unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/not_found"
|
|
"406":
|
|
description: "Not Acceptable - Can not delete last admin account"
|
|
|
|
/client:
|
|
parameters:
|
|
- $ref: "#/components/parameters/api_key"
|
|
put:
|
|
tags:
|
|
- "client (write)"
|
|
summary: "Update ipv4 client information based on request IP or body if present"
|
|
description: "If body is present, it will take precedence over the request IP. Response contains the newly set `ipv4` value."
|
|
operationId: "update_client_ip"
|
|
requestBody:
|
|
description: "An existing clients properties wil only be updated if the parameter is present."
|
|
required: false
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/client_update"
|
|
responses:
|
|
"200":
|
|
description: "OK"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/client_info"
|
|
"401":
|
|
$ref: "#/components/responses/unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/forbidden"
|
|
"406":
|
|
description: "Not Acceptable - IPv4 Address is invalid"
|
|
delete:
|
|
tags:
|
|
- "client (write)"
|
|
summary: "Delete an existing ipv4 client information"
|
|
description: "Response contains the previously set `ipv4` value before deletion."
|
|
operationId: "delete_client_ip"
|
|
responses:
|
|
"200":
|
|
description: "IP deleted"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/client_info"
|
|
"401":
|
|
$ref: "#/components/responses/unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/forbidden"
|
|
|
|
/clients/{client_name}:
|
|
parameters:
|
|
- $ref: "#/components/parameters/api_key"
|
|
- $ref: "#/components/parameters/client_name"
|
|
get:
|
|
tags:
|
|
- "client (read)"
|
|
summary: "Get ipv4 client information"
|
|
description: ""
|
|
operationId: "get_client_ip"
|
|
responses:
|
|
"200":
|
|
description: "OK"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/client_info"
|
|
"401":
|
|
$ref: "#/components/responses/unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/not_found"
|
|
|
|
/public/{client_name}:
|
|
parameters:
|
|
- $ref: "#/components/parameters/client_name"
|
|
get:
|
|
tags:
|
|
- "public"
|
|
summary: "Get ipv4 client information"
|
|
description: ""
|
|
operationId: "get_public_client_ip"
|
|
security: []
|
|
responses:
|
|
"200":
|
|
description: "OK"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/client_info"
|
|
"401":
|
|
$ref: "#/components/responses/unauthorized_public"
|
|
|
|
components:
|
|
|
|
# security
|
|
securitySchemes:
|
|
api_key:
|
|
in: "header"
|
|
type: "apiKey"
|
|
name: "X-API-Key"
|
|
|
|
# parameters
|
|
parameters:
|
|
api_key:
|
|
in: "header"
|
|
name: "X-API-Key"
|
|
required: true
|
|
schema:
|
|
type: "string"
|
|
client_name:
|
|
in: "path"
|
|
name: "client_name"
|
|
required: true
|
|
schema:
|
|
$ref: "#/components/schemas/client_name"
|
|
|
|
# responses:
|
|
responses:
|
|
## 401
|
|
unauthorized:
|
|
description: "Unauthorized - api_key must be present in Header"
|
|
unauthorized_public:
|
|
description: "Unauthorized - Ressource is not public"
|
|
## 403
|
|
forbidden:
|
|
description: "Forbidden - api_key not unauthorized"
|
|
## 404
|
|
not_found:
|
|
description: "Client not found"
|
|
|
|
# schemas:
|
|
schemas:
|
|
# objects
|
|
client:
|
|
type: "object"
|
|
required:
|
|
- "name"
|
|
properties:
|
|
name:
|
|
$ref: "#/components/schemas/client_name"
|
|
description:
|
|
$ref: "#/components/schemas/client_description"
|
|
permission:
|
|
$ref: "#/components/schemas/client_permission"
|
|
public_ip:
|
|
$ref: "#/components/schemas/client_public"
|
|
admin_client_api_key:
|
|
type: "object"
|
|
properties:
|
|
name:
|
|
$ref: "#/components/schemas/client_name"
|
|
api_key:
|
|
$ref: "#/components/schemas/client_api_key"
|
|
admin_client_info_array:
|
|
type: "array"
|
|
items:
|
|
$ref: "#/components/schemas/admin_client_info"
|
|
admin_client_info:
|
|
type: "object"
|
|
properties:
|
|
name:
|
|
$ref: "#/components/schemas/client_name"
|
|
description:
|
|
$ref: "#/components/schemas/client_description"
|
|
permission:
|
|
$ref: "#/components/schemas/client_permission"
|
|
public_ip:
|
|
$ref: "#/components/schemas/client_public"
|
|
ipv4:
|
|
$ref: "#/components/schemas/client_ipv4"
|
|
client_info:
|
|
type: "object"
|
|
properties:
|
|
name:
|
|
$ref: "#/components/schemas/client_name"
|
|
ipv4:
|
|
$ref: "#/components/schemas/client_ipv4"
|
|
client_update:
|
|
type: "object"
|
|
properties:
|
|
ipv4:
|
|
$ref: "#/components/schemas/client_ipv4"
|
|
# vars
|
|
client_name:
|
|
type: "string"
|
|
minLength: 3
|
|
maxLength: 20
|
|
example: "clientA"
|
|
description: "Unique client identifier"
|
|
client_permission:
|
|
type: "string"
|
|
example: "rw"
|
|
pattern: "^r?w?x?$"
|
|
description: |
|
|
Set permission of client.
|
|
`r`: `client (read)` access
|
|
`w`: `client (write)` access
|
|
`x`: `admin` access
|
|
*default: w*
|
|
client_description:
|
|
type: "string"
|
|
maxLength: 200
|
|
example: "Client across the river"
|
|
description: "default: ''"
|
|
client_public:
|
|
type: "boolean"
|
|
example: "false"
|
|
description: |
|
|
Set `true` to enable public read access
|
|
*default: false*
|
|
client_api_key:
|
|
type: "string"
|
|
example: "kakJwkejfiJkadkjhou35oi902ijsfli"
|
|
client_ipv4:
|
|
type: "string"
|
|
format: "ipv4"
|
|
example: "115.16.0.99"
|
|
pattern: "^(((25[0-5]|(2[0-4]|1[0-9]|[1-9]|)[0-9])(.(?!$)|$)){4})?$"
|
|
externalDocs:
|
|
description: "<rynDNS source code>"
|
|
url: "https://git.pdev.dev/pascal/ryndns"
|