From fe08c35134c0a7029a3bd97454bb006a35eb5e07 Mon Sep 17 00:00:00 2001 From: neil Date: Mon, 23 Nov 2020 22:17:50 +0800 Subject: [PATCH] Updated DNS API Dev Guide (markdown) --- DNS-API-Dev-Guide.md | 49 ++++++++++++++++++++++++-------------------- 1 file changed, 27 insertions(+), 22 deletions(-) diff --git a/DNS-API-Dev-Guide.md b/DNS-API-Dev-Guide.md index 70f69db..1cdf0a6 100644 --- a/DNS-API-Dev-Guide.md +++ b/DNS-API-Dev-Guide.md @@ -20,42 +20,44 @@ acme.sh --issue -d example.com --dns dns_myapi Here we go: ### 1. The cloudflare dns api is a recommended reference: - -https://github.com/Neilpang/acme.sh/blob/master/dnsapi/dns_cf.sh + Read it first: + https://github.com/Neilpang/acme.sh/blob/master/dnsapi/dns_cf.sh ### 2. The script file name must be `myapi.sh` -The file name must be in this format: `yourApiName.sh`, in this example, it should be `myapi.sh` + + The file name must be in this format: `yourApiName.sh`, in this example, it should be `myapi.sh` ### 3. The file can be placed in `acme.sh/` folder, or in `acme.sh/dnsapi/` subfolder. -If you want to contribute your script to `acme.sh` project, it must be placed in `acme.sh/dnsapi/` folder. -If you just want to use your script on your machine, you can put it in `.acme.sh/` or `.acme.sh/dnsapi/` folders. -acme.sh searches the script files in either the acme.sh home dir(`.acme.sh/`) or in the `dnsapi` subfolder(`.acme.sh/dnsapi`). + If you want to contribute your script to `acme.sh` project, it must be placed in `acme.sh/dnsapi/` folder. + If you just want to use your script on your machine, you can put it in `.acme.sh/` or `.acme.sh/dnsapi/` folders. + acme.sh searches the script files in either the acme.sh home dir(`.acme.sh/`) or in the `dnsapi` subfolder(`.acme.sh/dnsapi`). ### 4. The file shebang must be `sh` not `bash` -acme.sh is a `unix shell` script, not just a `bash` script. -If you want to contribute your script, the shebang must be: -```sh -#!/usr/bin/env sh -``` -After the installation, acme.sh could change the shebang to bash to get a better performance if you have bash on your machine. + acme.sh is a `unix shell` script, not just a `bash` script. -Of course, if you just use it on your own, it can be any valid shebang on your machine. It could be `sh` or `bash`, it's up to you. + If you want to contribute your script, the shebang must be: + ```sh + #!/usr/bin/env sh + ``` + After the installation, acme.sh could change the shebang to bash to get a better performance if you have bash on your machine. + + Of course, if you just use it on your own, it can be any valid shebang on your machine. It could be `sh` or `bash`, it's up to you. ### 5. There must be 2 functions in your script: -```sh -# Usage: add _acme-challenge.www.domain.com "XKrxpRBosdIKFzxW_CT3KLZNf6q0HG9i01zxXp5CPBs" -# Used to add txt record -dns_myapi_add() { } + ```sh + # Usage: add _acme-challenge.www.domain.com "XKrxpRBosdIKFzxW_CT3KLZNf6q0HG9i01zxXp5CPBs" + # Used to add txt record + dns_myapi_add() { } -# Usage: fulldomain txtvalue -# Used to remove the txt record after validation -dns_myapi_rm() { } + # Usage: fulldomain txtvalue + # Used to remove the txt record after validation + dns_myapi_rm() { } -``` -Actually, the `dns_myapi_add()` is required, but `dns_myapi_rm()` is optional. You can just write the add function at the beginning for testing purpose, it's `highly recommended` to implement the rm function too. Otherwise your txt records will increase 1 every 2 months. + ``` + Actually, the `dns_myapi_add()` is required, but `dns_myapi_rm()` is optional. You can just write the add function at the beginning for testing purpose, it's `highly recommended` to implement the rm function too. Otherwise your txt records will increase 1 every 2 months. ### 6. Guide for the add function @@ -253,6 +255,9 @@ Example: https://github.com/Neilpang/acme.sh/issues/2057 Please follow the guide: https://github.com/acmesh-official/acme.sh/wiki/DNS-API-Test +### 12. Others + 1. Don't use `grep -o` options, please use `_egrep_o()` function instead. + 2. Don't use `curl` or `wget`, please use `_get()` or `_post()` function instead. The `_post()` function can send `POST`, `PUT` or `UPDATE` requests. ## Style Guidelines