etherpadlite-golang

An interface for Etherpad-Lite's HTTP API for Go.

Version 1.1

Version 1.1 was released on September 2019. Two things were changed, one that might affect currently running code.

First, a new option to return all ethperpad errors as Go errors was introduced (see below). Second a typo was removed from the code. The constant WrongParameters had a missing e, so I fixed the spelling. Please rename this constant!

Installation

As of April 19 2020 go modules are supported. I've added version 1.1.0 as the first version with go mod support. Thus go get in the "old-fashioned way" mentioned below should not be used anymore.

Run go get github.com/FabianWe/etherpadlite-golang. Read the code documentation on GoDoc.

Note that you need Go >= 1.7 to use this package because the project uses the new context package that was formerly golang.org/x/net/context.

Supported API Versions

Though I haven't tested each and every function I'm very confident that all versions including version 1.2.13 are supported. Feedback is very welcome!

Usage

Here's a very simple example that should give you the idea. It creates a new pad called foo with some initial content.

import (
	"fmt"
	"log"

	etherpadlite "github.com/FabianWe/etherpadlite-golang"
)

func main() {
	pad := etherpadlite.NewEtherpadLite("your-api-key")
	response, err := pad.CreatePad(context.Background(), "foo", "Lorem ipsum dolor sit amet.")
	if err != nil {
		log.Fatal(err)
	}
	// note that an API error is still possible, see below
	fmt.Println(response.Code, response.Message, response.Data)
}

Here is an example that uses a context to cancel the request if five seconds have passed:

import (
	"context"
	"fmt"
	"log"
	"time"

	etherpadlite "github.com/FabianWe/etherpadlite-golang"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()
	pad := etherpadlite.NewEtherpadLite("your-api-key")
	response, err := pad.CreatePad(ctx, "foo", "Lorem ipsum dolor sit amet.")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Code, response.Message, response.Data)
}

All methods return two values: A Response containing the parsed JSON response and an error. If err != nil something went really wrong, for example the connection to the host failed or the context was cancelled while doing the request. It is still possible that something went wrong inside of etherpad. The response has a field of type ReturnCode. If this code is != EverythingOk (constant in the package) something went wrong inside of the etherpad client. So after checking for the error returned by the API function you can check for errors in the return code. So use something like

if response.Code != etherpadlite.EverythingOk {
	fmt.Println("Something went wrong...")
}

As of version 1.1 (September 2019) it's also possible to return all etherpad API errors directly instead of doing the check above. Just set RaiseEtherpadErrors = true on your EtherpadLite instance:

pad.RaiseEtherpadErrors = true

In this case all responses with error code != EverythingOk will be returned as an error of type EtherpadError.

You can configure the EtherpadLite element, for example configure the http.Client.

An EtherpadLite instance has the following fields:

• APIVersion: The HTTP API version. Defaults to 1.2.13. Note that this is a rather new version, if you have an older version of etherpad-lite you may have to adjust this!
• BaseParams: A map that contains the parameters that are sent in every request. The API key gets added in NewEtherpadLite.
• BaseURL: The URL pointing to the API of your pad, i.e. http://pad.domain/api. Defaults to http://localhost:9001/api in NewEtherpadLite.
• Client: The http.Client used to send the GET requests.
• RaiseEtherpadErrors: If set to true all errors from the etherpad API (return code != EverythingOk) will be returned as a Go error of type EtherpadError instead of being 'hidden' in the response.

All functions take as first argument a context.Context. If you pass ctx != nil the methods will get cancelled when ctx gets cancelled (i.e. return no Response and an error != nil). If you don't want to use a context at all simply set it to nil all the time. This is however not the optimal way of ignoring the context, according to the documentation you should always use a non-nil context, so better set it to context.Background or context.TODO.

If a method has an optional field, for example text in CreatePad, set the value to etherpadlite.OptionalParam if you don't want to use it. So to create a pad without text do:

response, err := pad.CreatePad(ctx, "foo", etherpadlite.OptionalParam)

If a method has a default argument, such as copyPad(sourceID, destinationID[, force=false]) setting the parameter to OptionalParam will set the value to its default.

It is safe to call the API methods simultaneously from multiple goroutines.

License

Copyright 2017 - 2019 Fabian Wenzelmann fabianwen@posteo.eu

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.