Demo • Getting started • Rest API • Configuration • Roadmap
## Getting Started This repo includes a [`Dockerfile`](Dockerfile) with an accompanying [`docker-compose.yml`](docker-compose.yml). To build and launch the container simply run: ```bash docker-compose up ``` Once the container is build and running it will create a default admin account and post its randomly generated api key to the console: ``` ryndns | No admin accounts in Database, adding default: admin ryndns | Created default admin with api_key: 3NJbP4tS.39b92576.062... ``` The API is now accessible at http://localhost:3000/rynDNS. ```bash # using httpie API_SERVER=http://localhost:3000/rynDNS API_KEY=X-API-Key:3NJbP4tS.39b92576.062142e6451df545d5034ca8f6050b80ff3e9689f20d5e45d72d160fa7e1cf32 # list all clients http get $API_SERVER/admin/clients $API_KEY # creating a client JSON_REQUEST_BODY='{ "name": "clientA", "description": "Client across the river", "permission": "rw", "public_ip": false }' http post $API_SERVER/admin/client $API_KEY <<< $JSON_REQUEST_BODY # Alternatively using query strings (be sure to encode special characters in the param values) API_KEY='X-API-Key=MdSUxrQQ.d5d40cd9.e2s1BsQEqmSE5MqyHYbDBVxGr/KY4BYIV5QkdjiCOF0=' CLIENT_PARAMS='name=clientA&description=Client+across+the+river&permission=rw&public_ip=false' http post "$API_SERVER/admin/client?$API_KEY&$CLIENT_PARAMS" ``` 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 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`. All requests except for `/public/*` require a valid `X-API-Key` header with appropriate permission. **Experimental:** All parameters (including `X-API-Key`) can be passed as query string. The following is a quick overview of the available commands. ### Admin Permission `x` * [`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 * [`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 * [`DELETE /admin/clients/{client_name}`](https://demo.api.pdev.dev/#/admin/delete_client) - Delete an existing client ### Client (write) 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 * [`DELETE /client`](https://demo.api.pdev.dev/#/client%20(write)/delete_client_ip) - Delete the requesting client's ipv4 information ### Client (read) Permission `r` * [`GET /clients/{client_name}`](https://demo.api.pdev.dev/#/client%20(read)/get_client_ip) - Get ipv4 client information ### Public Client attribute `public_ip: true` * [`GET /public/{client_name}`](https://demo.api.pdev.dev/#/public/get_public_client_ip) - Get ipv4 client information ## Configuration The `rynDNS` server can be configured with environment variables, these can also be set in the docker environment: ```bash # set to run app in subdirectory [default: /] RAILS_RELATIVE_URL_ROOT: /rynDNS # set maximum number of clients in db [default: 250] RAILS_MAX_CLIENTS: 250 # set custom api key prefix [default: randomly generated (saved and restored if using docker)] API_KEY_PREFIX: zW3If4s5 # set custom header name for api key [default: X-API-Key] API_KEY_HEADER: X-API-Key # set to reset the admin account, this will output a new api key on the console when starting the server [default: 0] RAILS_RESET_ADMIN: 1 # set app to run as demo [default: 0] RAILS_API_DEMO: 1 # [DOCKER only] set cycle to reset demo data [default: 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~~ (merged 297016e799) * add full test coverage for query strings (considered experimental until then) * add query strings to `api.yml` and additional examples * DNS Server in Docker container - resolve `client_name`s via DNS server