bindAPI/public/openapi/bindapi.json

526 lines
9.8 KiB
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}": {
"get": {
"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"
},
"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#"
]
}
}
}
}