{ "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#" ] } } } }