Git Product home page Git Product logo

rokka-go's Introduction

Rokka API client library for Go

A client to use rokka.io with Go.

GoDoc Build Status Coverage Status

CLI Installation & Usage

Downloads:

After downloading the binary, place it in a folder within your $PATH and rename it to rokka. Ensure the executable flag is set (e.g. on macOS and Linux execute chmod u+x rokka).

After that you can start the CLI.

# show commands and general help
$ rokka

# show help about a command (e.g. `login`)
$ rokka help login

# execute a command (e.g. `stacks list`)
$ rokka stacks list <organization name>

# get the raw json value of a command (e.g. to pipe it to another command)
$ rokka stacks list <organization name> -r

# show verbose request and response header/body
$ rokka stacks list <organization name> -v

Login

The login command can be used to store the API-Key. Without using login first, the API-Key has to be specified for all executed commands.

# configuration gets stored in $HOME/.rokka/config
$ rokka login --apiKey="ENTER-API-KEY-HERE"

# configuration gets stored in ./my-awesome-place
$ rokka login --apiKey="ENTER-API-KEY-HERE" --config=./my-awesome-place

# If you use a different location for storing your API key, don't forget to specify the config location for all executed commands
$ rokka stacks list <organization name> --config=./my-awesome-place

Advanced usage

The output of every command in the CLI is defined by a template written in Go's text/template language. In case you want to have a more specific output adapted to your needs you can overwrite that template on the fly by specifying the --template flag.

Example:

# list source images
$ rokka sourceimages list <organization>
Name                                           Hash                                      Details
rokka-pic.png                     AAAA937b9b057e419cf96c0696be8db9ed481BBB  image/png, 1260x840
foo.jpg                           AAAA3b1297cd6c272f5beb253921956b81007BBB  image/jpeg, 2498x1389

# list only the hashes (make sure you enter the newlines correctly)
$ rokka sourceimages list <organization> --template="
{{range .Items}}{{.Hash}}
{{end}}"

AAAA937b9b057e419cf96c0696be8db9ed481BBB
AAAA3b1297cd6c272f5beb253921956b81007BBB

Library Usage

Go >=1.8 is required.

$ go get github.com/rokka-io/rokka-go

The library can be imported using the package import path github.com/rokka-io/rokka-go/rokka. The godoc is published on godoc.org/github.com/rokka-io/rokka-go.

Basic usage example:

package main

import (
	"fmt"
	"os"

	"github.com/rokka-io/rokka-go/rokka"
)

func main() {
	c := rokka.NewClient(&rokka.Config{
		APIKey: "exampleAPIKey",
	})

	resp, err := c.GetOrganization("example")
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
	fmt.Printf("%s", resp.ID)
}

Automatic retries

The library supports a mechanism to auto retry requests if they fail. The retries happen if either a HTTP, network or transport error occurs, or a status code of 429 (too many requests), 502 (bad gateway), 503 (service unavailable), or 504 (gateway timeout) has been received.

You can enable auto retry only on certain requests or, by storing the return value of AutoRetry() for all requests.

c := rokka.NewClient(&rokka.Config{
	APIKey: "exampleAPIKey",
})

// enable for one request
resp, err := c.AutoRetry().GetOrganization("example")

// store return value and use it for all requests
retryingClient := c.AutoRetry()
retryingClient.GetOrganization("example")

Contributing

Dependencies

This project uses go modules. Place this project outside your $GOPATH. Dependencies will be downloaded automatically upon first go run or go build.

Development

# Run CLI during development
$ go run ./cmd/rokka/main.go

# Build platform specific executables
$ GOOS=darwin go build -o ./bin/rokka ./cmd/rokka
$ GOOS=linux go build -o ./bin/rokka ./cmd/rokka
$ GOOS=windows go build -o ./bin/rokka ./cmd/rokka

# Update (auto-generate) rokka/operations_objects.go
$ go generate ./rokka

# Run tests
$ go test ./...

rokka-go's People

Contributors

chregu avatar dbu avatar dpacassi avatar mweibel avatar pstadler avatar thepanz avatar

Stargazers

avatar avatar avatar avatar

Watchers

avatar avatar avatar avatar avatar

Forkers

thepanz

rokka-go's Issues

Sourceimages search rangeable querystring params

Searching sourceimages can be done on various fields in various ways. How we currently implement it is that you can pass a string for each of those values and define on your own whether you want to use a range or just a value.
This is not very typesafe and could be made easier by the library. Question is: is it worth the effort?
An example of how we could implement that for the string type (untested code):

type MaybeRangedString struct {
	Val string
	Range RangedString
}

func (mrs *MaybeRangedString) EncodeValues(key string, v *url.Values) error {
	if mrs.Val != "" {
		v.Set(key, mrs.Val)
		return nil
	} else {
		return mrs.Range.Encode(key, v)
	}
}

// RangedString is a string with from and to values.
// FromExclusive/ToExclusive define how the query string range is passed.
//
// From needs to be set always.
type RangedString struct {
	From          string
	To            string
	FromExclusive bool
	ToExclusive   bool
}

// EncodeValues implements query.Encoder for custom range encoding.
func (rs *RangedString) EncodeValues(key string, v *url.Values) error {
	s := ""
	if rs.FromExclusive {
		s += "{"
	} else {
		s += "["
	}
	s += rs.From
	if rs.To != "" {
		s += "," + rs.To
	}
	if rs.ToExclusive {
		s += "}"
	} else {
		s += "]"
	}
	v.Set(key, s)

	return nil
}

Similar implementations would have to be provided for the other types, though some things can probably be reused accross the types.

Opinions?

missing new line in CLI output 

chregu@pri14:~/tmp$ rokka stacks delete $YOUR_ORG test
Stack successfully deletedchregu@pri14:~/tmp$

There should be a new line after "deleted"

Show image URL for sourceimages

to be able to immediately open the sourceimage in the browser and see how it looks like.
Probably needs some way to use the image host to generate the URL. May not be possible just with a template change.

Nicely formatted CLI output

(Not just a JSON output anymore)

  • By default CLI commands return a nicely formatted, human readable output
  • A flag is supported to retrieve the JSON response (e.g. -raw)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.