diff --git a/DNS-API-Dev-Guide.md b/DNS-API-Dev-Guide.md index f8b91bc..bfadd26 100644 --- a/DNS-API-Dev-Guide.md +++ b/DNS-API-Dev-Guide.md @@ -5,7 +5,7 @@ This guide is to help any developer interested to build a brand new DNS API for ## Some useful tips 1. It's normal to run into errors, so do use `--debug 2` when testing. For e.g., `acme.sh --issue --debug 2 -d example.com --dns dns_myapi` -2. It's normal to burst rate limits for letsencrypt, so do use `--staging` when testing. For e.g., `acme.sh --issue --staging --debug 2 -d example.com --dns dns_myapi` Read [issue 1787](https://github.com/acmesh-official/acme.sh/issues/1787) for details. Remember to remove `--staging` after testing. +2. It's normal to burst rate limits for Let's Encrypt, so do use `--staging` when testing. For e.g., `acme.sh --issue --staging --debug 2 -d example.com --dns dns_myapi` Read [issue 1787](https://github.com/acmesh-official/acme.sh/issues/1787) for details. Remember to remove `--staging` after testing. Let's assume your API name is `myapi`, and you will use your API like: @@ -34,7 +34,6 @@ Here we go: acme.sh searches the script files in either the acme.sh home dir(`.acme.sh/`) or in the `dnsapi` subfolder(`.acme.sh/dnsapi`). - ### 4. There must be 2 functions in your script: ```sh @@ -47,7 +46,7 @@ Here we go: 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 purposes, 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 purposes, it's `highly recommended` to implement the rm function too. Otherwise, your TXT records will increase 1 every 2 months. ### 5. Guide for the add function @@ -100,8 +99,8 @@ The full domain could be in either one of the following formats: 4. `_acme-challenge.www.example.co.uk` 5. `_acme-challenge.sub1.sub2.www.example.co.uk` 6. `sub1.sub2.example.co.uk` -7. `example.com` ( For [DNS alias mode](https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode)) -8. `example.co.uk` ( For [DNS alias mode](https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode)) +7. `example.com` (For [DNS alias mode](https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode)) +8. `example.co.uk` (For [DNS alias mode](https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode)) For most of the DNS providers, you must determine which part is the domain root zone(example.com or example.co.uk), and which part is the subdomain(_acme-challenge or _acme-challenge.www) @@ -110,8 +109,7 @@ Please make sure you can handle all the formats above.* A good practice is to list all your root zones through your DNS API, then compare and detect which part is the root zone. Then the rest is the subdomain. -See: -https://github.com/acmesh-official/acme.sh/blob/master/dnsapi/dns_cf.sh#L142 +See: https://github.com/acmesh-official/acme.sh/blob/master/dnsapi/dns_cf.sh#L142 ```sh dns_myapi_add() { @@ -136,9 +134,9 @@ So, you can just use the HTTP GET/POST/PUT/DELETE method to call their API to ad acme.sh defined two functions to make http GET/POST/PUT/DELETE connections. -see: -https://github.com/acmesh-official/acme.sh/blob/8ded524236347d5a1f7a3169809cab9cf363a1c8/acme.sh#L2013 -https://github.com/acmesh-official/acme.sh/blob/8ded524236347d5a1f7a3169809cab9cf363a1c8/acme.sh#L1887 +See: +- https://github.com/acmesh-official/acme.sh/blob/8ded524236347d5a1f7a3169809cab9cf363a1c8/acme.sh#L2013 +- https://github.com/acmesh-official/acme.sh/blob/8ded524236347d5a1f7a3169809cab9cf363a1c8/acme.sh#L1887 ``` _get() {} @@ -150,8 +148,8 @@ You can use them directly. Please take care that the `_post()` function can send POST/PUT/DELETE requests, not just `POST`. See: -https://github.com/acmesh-official/acme.sh/blob/975a7359a23cd5f8335aca58ceab552d8d967ea7/dnsapi/dns_infoblox.sh#L85 -https://github.com/acmesh-official/acme.sh/blob/ded7a5438ce94c4dd0435068de5c0c384b60e4dd/dnsapi/dns_cf.sh#L73 +- https://github.com/acmesh-official/acme.sh/blob/975a7359a23cd5f8335aca58ceab552d8d967ea7/dnsapi/dns_infoblox.sh#L85 +- https://github.com/acmesh-official/acme.sh/blob/ded7a5438ce94c4dd0435068de5c0c384b60e4dd/dnsapi/dns_cf.sh#L73 Do not use `curl` or `wget` directly in your script. @@ -177,7 +175,7 @@ _acme-challenge.example.com. 3600 IN TXT "XhVGx_0VVeR5yiaGLHHXrRl2sAbZhI7IugMSdb #### 5. Additional HTTP headers. -Your HTTP method call may require additional headers for Authorization, ContentType, Accept, Cookies, etc. for the DNS providers api to add/remove the txt record. You can export _H*n* (_H1, _H2, _H3, etc.) environment variables with the [HTTP header](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields) needed: +Your HTTP method call may require additional headers for Authorization, ContentType, Accept, Cookies, etc. for the DNS providers API to add/remove the txt record. You can export _H*n* (_H1, _H2, _H3, etc.) environment variables with the [HTTP header](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields) needed: ```sh ... @@ -221,8 +219,7 @@ Please take care that the rm function and add function are called in 2 different You must re-do all the preparations of the add function here too. -See: -https://github.com/acmesh-official/acme.sh/blob/8ded524236347d5a1f7a3169809cab9cf363a1c8/dnsapi/dns_cf.sh#L106 +See: https://github.com/acmesh-official/acme.sh/blob/8ded524236347d5a1f7a3169809cab9cf363a1c8/dnsapi/dns_cf.sh#L106 ### 8. Please also check this bug to support the V2 wildcard cert: