Update and improve documentation

`find-domains` has been added to the list of covered endpoints. The
README usage section has been extended to show some basic operations
with records, and point to documentation and tests for learning usage,
and to the Njalla Terraform provider for actual code usage examples.
This commit is contained in:
Sighery 2021-09-12 00:10:59 +02:00
parent cf5fdbb592
commit ea449f0dda
2 changed files with 78 additions and 3 deletions

View file

@ -11,6 +11,7 @@ are:
* `add-record`
* `edit-record`
* `remove-record`
* `find-domains`
**TO NOTE**: Even though `record` methods are implemented, I'm fairly certain
they'll fail (silently or not) in some cases. I deal mostly with `TXT`, `MX`,
@ -28,6 +29,11 @@ cover all types of DNS records), as long as they're all tested and documented.
### Usage
Most of the methods are pretty self-explanatory if you read the documentation
and read the function signature. Some of the most "complex" operations, like
creating/updating records can be figured out from the tests. But here's some
examples:
```golang
package main
@ -41,14 +47,79 @@ func main() {
token := "api-token"
domain := "your-domain"
records, err := ListRecords(token, domain)
if err != nil {
fmt.Println(err)
// 1. Listing records in a domain
records, err1 := gonjalla.ListRecords(token, domain)
if err1 != nil {
fmt.Println(err1)
}
// It will print an array of gonjalla.Record
fmt.Println(records)
// 2. Adding a new record to a domain
priority := 10
adding := gonjalla.Record{
Name: "@",
Type: "MX",
Content: "testing.com",
TTL: 10800,
Priority: &priority,
}
confirmation, err2 := gonjalla.AddRecord(token, domain, adding)
if err2 != nil {
fmt.Println(err2)
}
// confirmation will be a gonjalla.Record with the response from the
// server, so it should be pretty similar to your starting
// gonjalla.Record but this will contain the ID filled in, which is
// needed for updates
fmt.Println(confirmation)
// 3. Updating a record of a given domain
// Let's assume we got the ID of the record created in step 2
// and we want to change either some or all fields
id_we_look_for := confirmation.ID
// The edit method updates all the fields due to limitations of the
// API. Get the record from the API if you only want to change some,
// but not all, fields
for _, record := range records {
if record.ID == id_we_look_for {
record.Content = "edited-value"
record.TTL = 900
err3 := gonjalla.EditRecord(token, domain, record)
if err3 != nil {
fmt.Println(err3)
}
}
}
// If you don't care about overwriting previous values
new_priority := 20
editing := gonjalla.Record{
ID: id_we_look_for,
Name: "@",
Type: "MX",
Content: "edited-thing",
TTL: 300,
Priority: &new_priority,
}
err4 := gonjalla.EditRecord(token, domain, editing)
if err4 != nil {
fmt.Println(err4)
}
}
```
Some actual code making use of this library (mainly dealing with records) can
also be seen at the [Njalla Terraform provider].
[Njalla]: https://njal.la
[official API]: https://njal.la/api/
[Njalla Terraform provider]: https://github.com/Sighery/terraform-provider-njalla

View file

@ -94,6 +94,10 @@ func RemoveRecord(token string, domain string, id int) error {
// its filled fields to send to Njalla.
// So, if you want to only change a given field, get the `Record` object from
// say ListRecords, change the one field you want, and then pass that here.
//
// Note that the record type cannot be changed, so if you want to do so, you'll
// have to remove and create the record again under a different type. Trying to
// change the record type will just return an API error.
func EditRecord(token string, domain string, record Record) error {
marshal, err := json.Marshal(record)
if err != nil {