bindAPI/public/openapi/bindapi.json

{
	"openapi": "3.0.2",
	"info": {
		"title": "bindAPI",
		"version": "0.0.2",
		"description": "TODO …",
		"contact": {
			"name": "Micha Espey",
			"email": "tracer@24unix.net"
		}
	},
	"servers": [
		{
			"url": "{schema}://{hostname}/api",
			"description": "The bindAPI URL.",
			"variables": {
				"schema": {
					"enum": [
						"https",
						"http"
					],
					"default": "https"
				},
				"hostname": {
					"default": "ns1.24unix.net"
				}
			}
		}
	],
	"tags": [
		{
			"name": "Server"
		},
		{
			"name": "DNS"
		},
		{
			"name": "Domains"
		}
	],
	"security": [
		{
			"ApiKeyAuth": []
		}
	],
	"paths": {
		"/ping": {
			"get": {
				"tags": [
					"Server"
				],
				"summary": "Returning pong.",
				"description": "Can be used to check API or server availability.",
				"operationId": "getPong",
				"responses": {
					"200": {
						"$ref": "#/components/responses/ping"
					},
					"401": {
						"$ref": "#/components/responses/401-unauthorized"
					}
				},
				"security": [
					{
						"Authorization": [
							"read"
						]
					}
				]
			}
		},
		"/dyndns/{hostname}": {
			"post": {
				"tags": [
					"DNS"
				],
				"summary": "Updated a DynDNS host.",
				"description": "Updates a predefined custom DNS entry.",
				"operationId": "updateDynDNS",
				"parameters": [
					{
						"name": "hostname",
						"in": "path",
						"required": true,
						"schema": {
							"type": "string"
						}
					}
				],
				"requestBody": {
					"$ref": "#/components/requestBodies/dyndns-put"
				},
				"responses": {
					"200": {
						"description": "OK"
					},
					"204": {
						"description": "No Content"
					},
					"401": {
						"description": "API key is missing or invalid."
					},
					"404": {
						"description": "Domain not found."
					}
				},
				"security": [
					{
						"Authorization": []
					}
				]
			}
		},
		"/domains": {
			"get": {
				"tags": [
					"Domains"
				],
				"summary": "Returns all domains.",
				"description": "Returns information of a single domain specified by its domain name.",
				"operationId": "getDomains",
				"responses": {
					"200": {
						"$ref": "#/components/responses/domain-array"
					},
					"401": {
						"$ref": "#/components/responses/401-unauthorized"
					}
				}
			},
			"post": {
				"tags": [
					"Domains"
				],
				"summary": "Create a domain.",
				"description": "Create a new domain.",
				"operationId": "putDomains",
				"requestBody": {
					"$ref": "#/components/requestBodies/domain-post"
				},
				"responses": {
					"201": {
						"$ref": "#/components/responses/201-created"
					},
					"400": {
						"$ref": "#/components/responses/400-bad-request"
					},
					"401": {
						"$ref": "#/components/responses/401-unauthorized"
					}
				}
			}
		},
		"/domains/{id}": {
			"get": {
				"tags": [
					"Domains"
				],
				"summary": "Returns a single domain.",
				"description": "Returns information of a single domain specified by its ID.",
				"operationId": "getSingleDomain",
				"parameters": [
					{
						"name": "id",
						"in": "path",
						"required": true,
						"schema": {
							"type": "string"
						}
					}
				],
				"responses": {
					"200": {
						"$ref": "#/components/responses/200-ok"
					},
					"400": {
						"$ref": "#/components/responses/400-bad-request"
					},
					"401": {
						"$ref": "#/components/responses/401-unauthorized"
					}
				}
			},
			"put": {
				"tags": [
					"Domains"
				],
				"summary": "Updates a domain.",
				"description": "Updates a domain. Only supplied fields will be updated, existing won't be affected.",
				"operationId": "putDomain",
				"parameters": [
					{
						"name": "id",
						"in": "path",
						"required": true,
						"schema": {
							"type": "string"
						}
					}
				],
				"requestBody": {
					"$ref": "#/components/requestBodies/domain-put"
				},

				"responses": {
					"200": {
						"description": "OK"
					},
					"401": {
						"description": "API key is missing or invalid."
					},
					"404": {
						"description": "Domain not found."
					}
				},
				"security": [
					{
						"Authorization": []
					}
				]
			},
			"delete": {
				"tags": [
					"Domains"
				],
				"summary": "Deletes a domain.",
				"description": "Deletes a domain.",
				"operationId": "73c6c14e6d84f759d2e09029cb7ab2be",
				"parameters": [
					{
						"name": "id",
						"in": "path",
						"required": true,
						"schema": {
							"type": "string"
						}
					}
				],
				"responses": {
					"204": {
						"$ref": "#/components/responses/204-no-content"
					},
					"401": {
						"$ref": "#/components/responses/401-unauthorized"
					},
					"404": {
						"$ref": "#/components/responses/404-not-found"
					}
				},				"security": [
					{
						"Authorization": []
					}
				]
			}
		},
		"/domains/name/{name}": {
			"get": {
				"tags": [
					"Domains"
				],
				"summary": "Returns a single domain by name.",
				"description": "Returns information of a single domain specified by its domain name.",
				"operationId": "getSingleDomainByName",
				"parameters": [
					{
						"name": "name",
						"in": "path",
						"required": true,
						"schema": {
							"type": "string"
						}
					}
				],
				"responses": {
					"200": {
						"$ref": "#/components/responses/200-ok"
					},
					"400": {
						"$ref": "#/components/responses/400-bad-request"
					},
					"401": {
						"$ref": "#/components/responses/401-unauthorized"
					}
				}
			}
		}
	},
	"components": {
		"securitySchemes": {
			"Authorization": {
				"type": "apiKey",
				"description": "Authentication Token",
				"name": "X-API-Key",
				"in": "header"
			}
		},
		"requestBodies": {
			"dyndns-put": {
				"required": true,
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/dyndns"
						},
						"example": {
							"a": "1.2.3.4",
							"aaaa": "1bad::babe"
						}
					}
				}
			},
			"domain-post": {
				"required": true,
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/domain"
						}
					}
				}
			},
			"domain-put": {
				"required": true,
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/domain"
						},
						"example": {
							"name": "example.com",
							"panel_id": "8"
						}
					}
				}
			}
		},
		"responses": {
			"ping": {
				"description": "OK.",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/ping"
						}
					}
				}
			},
			"domain": {
				"description": "OK.",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/domain"
						}
					}
				}
			},
			"domain-array": {
				"description": "OK.",
				"content": {
					"application/json": {
						"schema": {
							"type": "array",
							"items": {
								"$ref": "#/components/schemas/domain"
							}
						}
					}
				}
			},
			"200-ok": {
				"description": "OK."
			},
			"200-ok-updated": {
				"description": "OK.",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/created"
						},
						"example": {
							"id": 8
						}
					}
				}
			},
			"201-created": {
				"description": "Created.",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/created"
						},
						"example": {
							"id": 8
						}
					}
				}
			},
			"204-no-content": {
				"description": "No content."
			},
			"400-bad-request": {
				"description": "Bad request.",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/error"
						},
						"example": {
							"code": "400 Bad Request",
							"message": "Invalid request body."
						}
					}
				}
			},
			"401-unauthorized": {
				"description": "Unauthorized.",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/error"
						},
						"example": {
							"code": "401 Unauthorized",
							"message": "API key is missing or invalid."
						}
					}
				}
			},
			"404-not-found": {
				"description": "The specified resource was not found.",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/error"
						},
						"example": {
							"code": "404 Not Found",
							"message": "The specified resource was not found."
						}
					}
				}
			}
		},
		"schemas": {
			"ping": {
				"type": "object",
				"properties": {
					"response": {
						"type": "string",
						"example": "pong"
					}
				}
			},
			"dyndns": {
				"type": "object",
				"properties": {
					"a": {
						"type": "string",
						"example": "1.2.3.4"
					},
					"aaaa": {
						"type": "string",
						"example": "1bad::babe"
					}
				}

			},
			"domain": {
				"description": "Representation of a domain.\n",
				"type": "object",
				"properties": {
					"id": {
						"type": "integer",
						"readOnly": true,
						"description": "The ID of the domain.",
						"example": 8
					},
					"name": {
						"type": "string",
						"description": "The ASCII representation of the domain.",
						"example": "example.com"
					},
					"panel_id": {
						"type": "integer",
						"description": "The KeyHelp Panel ID. Either this or at least one IP address is required",
						"example": 4
					},
					"a": {
						"type": "string",
						"readOnly": true,
						"description": "The IPv4 address.",
						"example": "12.13.14.15"
					},
					"aaaa": {
						"type": "string",
						"readOnly": true,
						"description": "The IPv6 address.",
						"example": "1bad::babe"
					}
				}
			},
			"created": {
				"type": "object",
				"properties": {
					"id": {
						"type": "integer"
					}
				}
			},
			"error": {
				"type": "object",
				"properties": {
					"code": {
						"type": "string"
					},
					"message": {
						"type": "string"
					}
				},
				"required": [
					"code",
					"message#"
				]
			}
		}
	}
}