diff --git a/README.md b/README.md index 256ef95..7eac1cd 100644 --- a/README.md +++ b/README.md @@ -6,18 +6,18 @@ 6. [Conclusion](#conclusion) -# Overview +# 1. Overview This package provides an API for the Bind nameserver. It consists of two parts, the API itself and a CLI tool to configure the available functions. -# Features +# 2. Features -## CLI +## 2.1. CLI -![Php Interpreter](https://bindapi.24unix.net/assets/bindAPI_cli.png) +![CLI Interface](https://bindapi.24unix.net/assets/bindAPI_cli.png) The CLI is used to perform configuration and some checks: @@ -30,7 +30,7 @@ The CLI is used to perform configuration and some checks: - Create: Adds a new panel to the configuration - Update: Changes one or more parameters of the panel - Delete: Deletes the given panel - - ApiPing: Calls the /ping endpoint of the given server + - ApiPing: Calls the /ping endpoint of the given server or all if no Panel is specified - some additional API call might be added * nameservers - similar to panels, but for the nameservers @@ -39,14 +39,66 @@ The CLI is used to perform configuration and some checks: * apikeys - manage the keys to access this nameserver via API -API +# 2.2. API + +![OpenAPI](https://bindapi.24unix.net/assets/bindAPI_api1.png) + +The APi is a RESTful API, there is a self explaining Swagger/OpenAPI available. + +On the site you can authorize with an API key (creation of the key is described later in this document). +![Authorize](https://bindapi.24unix.net/assets/bindAPI_api2.png) +![Enter Apikey](https://bindapi.24unix.net/assets/bindAPI_api3.png) +After successful authorization you can use the APi via the OpenAPI Interface, e.g. call the /ping endpoint to check if the API is alive. +You have to click on „Try it out“: + +![Try it out](https://bindapi.24unix.net/assets/bindAPI_api4.png) + +Of course, you can issue the same command in your shell: + +` +curl -X 'GET' \ +'https://ns1.24unix.net/api/ping' \ +-H 'accept: application/json' \ +-H 'X-API-Key: 61f27a57c9d1f.[truncated]' +` + +A helpful tool when dealing with API is [Postman](https://https://www.postman.com/), if offers the same options as from the OpenAPI interface or via shell with curl. + +![Php Interpreter](https://bindapi.24unix.net/assets/bindAPI_api5.png) -# Installation +# 3. Installation + +You can install the bindAPi on either a standalone server or an existing KeyHelp Panel. +However, slave zones are only managed for masters which lie on Keyhelp panels. + +## 3.1. Installation on a KeyHelp panel + +In KeyHelp, install PHP 8.1. +This is mandatory, the API relies on features only available since PHP 8.0. +It might run on PHP 8.0 but has not been tested as there is no reason not to install PHP 8.1. + +So head over to: +Settings => Configuration => Feature Settings => PHP Interpreter +![Php Interpreter](https://bindapi.24unix.net/assets/bindAPI_php1.png) + + +Set the checkmark and press Save. + +Wait about a minute, the installation is started via a cronjob which runs every minute. +![Install Php Interpreter](https://bindapi.24unix.net/assets/bindAPI_php2.png) + +xxx +![Php Interpreter](https://bindapi.24unix.net/assets/bindAPI_php3.png) + +Next create a domain, e.g. ns1.24unix.net: + +![Php Interpreter](https://bindapi.24unix.net/assets/bindAPI_php2.png) + # Configuration @@ -57,20 +109,11 @@ API # Conclusion -In KeyHelp, install PHP 8.1 -Settings => Configuration => Feature Settings => PHP Interpreter -![Php Interpreter](https://bindapi.24unix.net/assets/bindAPI_php1.png) -![Php Interpreter](https://bindapi.24unix.net/assets/bindAPI_php2.png) - -![Php Interpreter](https://bindapi.24unix.net/assets/bindAPI_php3.png) ![Php Interpreter](https://bindapi.24unix.net/assets/bindAPI_php4.png) -Set the checkmark and press Save. - -Wait about a minute, the installation is started via a cronjob which runs every minute.