[mod] modified readme
- removed zero width spaces - added some more examples and roadmap
This commit is contained in:
53
README.md
53
README.md
@@ -4,7 +4,7 @@
|
|||||||
A simplistic Dynamic DNS-ish server.
|
A simplistic Dynamic DNS-ish server.
|
||||||
</h4>
|
</h4>
|
||||||
|
|
||||||
`rynDNS` is a simple REST-API for `name` to `ip` resolving in the spirit of Dynamic DNS. Clients can `PUT` their `ipv4` address up to be read by other clients. Access is controlled via `api_key` and permissions (`read`, `write`, `admin`).
|
`rynDNS` is a simple REST-API for `name` to `ip` resolving in the spirit of Dynamic DNS. Clients can `PUT` their `ipv4` address up to be read by other clients. Access is controlled via `api_key` and permissions (`read`, `write`, `admin`). No special client side application needed, just something to do a `POST` request like `wget`, `curl` or `httpie`.
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<strong>
|
<strong>
|
||||||
@@ -12,6 +12,7 @@
|
|||||||
• <a href="#getting-started">Getting started</a>
|
• <a href="#getting-started">Getting started</a>
|
||||||
• <a href="#rest-api">Rest API</a>
|
• <a href="#rest-api">Rest API</a>
|
||||||
• <a href="#configuration">Configuration</a>
|
• <a href="#configuration">Configuration</a>
|
||||||
|
• <a href="#roadmap">Roadmap</a>
|
||||||
</strong>
|
</strong>
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
@@ -44,6 +45,36 @@ JSON_REQUEST_BODY='{
|
|||||||
}'
|
}'
|
||||||
http post $API_SERVER/admin/client $API_KEY <<< $JSON_REQUEST_BODY
|
http post $API_SERVER/admin/client $API_KEY <<< $JSON_REQUEST_BODY
|
||||||
```
|
```
|
||||||
|
Updating a write client's `ipv4`:
|
||||||
|
```bash
|
||||||
|
# using httpie
|
||||||
|
API_SERVER=http://localhost:3000/rynDNS
|
||||||
|
API_KEY=X-API-Key:zW3If4s5.3d6129cc.48d41d2a28b16a9a274d3f407026aee2b82cddbb3c11a5496ffe329c78e5d54b
|
||||||
|
|
||||||
|
# automatically set ip based on request itself
|
||||||
|
http put $API_SERVER/client $API_KEY
|
||||||
|
|
||||||
|
# set a custom ip for the client
|
||||||
|
JSON_REQUEST_BODY='{
|
||||||
|
"ipv4": "115.16.0.99"
|
||||||
|
}'
|
||||||
|
http put $API_SERVER/client $API_KEY <<< $JSON_REQUEST_BODY
|
||||||
|
```
|
||||||
|
Reading a write client's `ipv4` with a read client:
|
||||||
|
```bash
|
||||||
|
# using httpie
|
||||||
|
API_SERVER=http://localhost:3000/rynDNS
|
||||||
|
API_KEY=X-API-Key:zW3If4s5.28aef5cb.d502cb94ba0802c6363f95ecb3a70de7e2e4b889779e435b7c033f2c72ed4f20
|
||||||
|
CLIENT_NAME=write_client
|
||||||
|
|
||||||
|
http get $API_SERVER/clients/$CLIENT_NAME $ API_KEY
|
||||||
|
|
||||||
|
# returns clients name and ipv4 as json
|
||||||
|
#{
|
||||||
|
# "name": "write_client",
|
||||||
|
# "ipv4": "115.16.0.99"
|
||||||
|
#}
|
||||||
|
```
|
||||||
## REST API
|
## REST API
|
||||||
A detailed and interactive specification can be found in the [demo](https://demo.api.pdev.dev) which is a render of the OpenAPI specification [api.yml](api.yml) with `swager-ui`.
|
A detailed and interactive specification can be found in the [demo](https://demo.api.pdev.dev) which is a render of the OpenAPI specification [api.yml](api.yml) with `swager-ui`.
|
||||||
|
|
||||||
@@ -55,26 +86,26 @@ The following is a quick overview of the available commands.
|
|||||||
Permission `x`
|
Permission `x`
|
||||||
|
|
||||||
* [`POST /admin/client`](https://demo.api.pdev.dev/#/admin/create_client) - Create or update a client and retrieve a new API key
|
* [`POST /admin/client`](https://demo.api.pdev.dev/#/admin/create_client) - Create or update a client and retrieve a new API key
|
||||||
* [`PUT /admin/client`](https://demo.api.pdev.dev/#/admin/update_client) - Update an existing client
|
* [`PUT /admin/client`](https://demo.api.pdev.dev/#/admin/update_client) - Update an existing client
|
||||||
* [`GET /admin/clients`](https://demo.api.pdev.dev/#/admin/get_all_client) - Retrieve all clients information
|
* [`GET /admin/clients`](https://demo.api.pdev.dev/#/admin/get_all_client) - Retrieve all clients information
|
||||||
* [`GET /admin/clients/{client_name}`](https://demo.api.pdev.dev/#/admin/get_client) - Retrieve client information
|
* [`GET /admin/clients/{client_name}`](https://demo.api.pdev.dev/#/admin/get_client) - Retrieve client information
|
||||||
* [`DELETE /admin/clients/{client_name}`](https://demo.api.pdev.dev/#/admin/delete_client) - Delete an existing client
|
* [`DELETE /admin/clients/{client_name}`](https://demo.api.pdev.dev/#/admin/delete_client) - Delete an existing client
|
||||||
|
|
||||||
### Client (write)
|
### Client (write)
|
||||||
Permission `w`
|
Permission `w`
|
||||||
|
|
||||||
* [`PUT /client`](https://demo.api.pdev.dev/#/client%20(write)/update_client_ip) - Update ipv4 client information based on request IP or body if present
|
* [`PUT /client`](https://demo.api.pdev.dev/#/client%20(write)/update_client_ip) - Update ipv4 client information based on request IP or body if present
|
||||||
* [`DELETE /client`](https://demo.api.pdev.dev/#/client%20(write)/delete_client_ip) - Delete the requesting client's ipv4 information
|
* [`DELETE /client`](https://demo.api.pdev.dev/#/client%20(write)/delete_client_ip) - Delete the requesting client's ipv4 information
|
||||||
|
|
||||||
### Client (read)
|
### Client (read)
|
||||||
Permission `r`
|
Permission `r`
|
||||||
|
|
||||||
* [`GET /clients/{client_name}`](https://demo.api.pdev.dev/#/client%20(read)/get_client_ip) - Get ipv4 client information
|
* [`GET /clients/{client_name}`](https://demo.api.pdev.dev/#/client%20(read)/get_client_ip) - Get ipv4 client information
|
||||||
|
|
||||||
### Public
|
### Public
|
||||||
Client attribute `public_ip: true`
|
Client attribute `public_ip: true`
|
||||||
|
|
||||||
* [`GET /public/{client_name}`](https://demo.api.pdev.dev/#/public/get_public_client_ip) - Get ipv4 client information
|
* [`GET /public/{client_name}`](https://demo.api.pdev.dev/#/public/get_public_client_ip) - Get ipv4 client information
|
||||||
|
|
||||||
## Configuration
|
## Configuration
|
||||||
|
|
||||||
@@ -96,3 +127,9 @@ RAILS_API_DEMO: 1
|
|||||||
# [DOCKER only] set cycle to reset demo data [default: 60m]
|
# [DOCKER only] set cycle to reset demo data [default: 60m]
|
||||||
RAILS_DEMO_RESET: 60m
|
RAILS_DEMO_RESET: 60m
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Roadmap
|
||||||
|
|
||||||
|
* `Public Mode` - to allow for quick deployment without having to create clients/api-keys in a trusted environment (see #1)
|
||||||
|
* Support Query Strings - as alternative to api key in header and json body
|
||||||
|
* DNS Server in Docker container - resolve `client_name`s via DNS server
|
||||||
|
|||||||
Reference in New Issue
Block a user