Manage your Kanka campaign or build tools for other creators with the thoroughly tested and documented kanka package.

The kanka package provides a client to handle all communication with the Kanka API.

The package is structured into convenient and discoverable services for managing characters, locations, organizations, events, and much more.

If you do not have Go installed yet, you can find installation instructions here.

To pull the most recent version of kanka, use go get.

go get github.com/Henry-Sarabia/kanka

Then import the package into your project as you normally would.

import "github.com/Henry-Sarabia/kanka"

To use the kanka package, you need a Kanka API key. If you do not have a key yet, you can follow the instructions here to get one.

Create a client with your API key to start communicating with the Kanka API.

c, err := kanka.NewClient("YOUR_API_KEY", nil)

If you need to use a preconfigured HTTP client, simply pass its address to the NewClient function.

c, err := kanka.NewClient("YOUR_API_KEY", &custom)

The client contains a separate service for working with each of the Kanka API endpoints. Each service has a set of functions to retrieve, list, create, update, or delete campaign data.

To start communicating with the Kanka API, choose a service and call one of its functions.

Take the Campaigns service for this example.

To retrieve a list of the current user's campaigns, use the Index function.

cmps, err := c.Campaigns.Index()

You now have access to a list of the user's campaigns via cmps.

To retrieve a specific entity from a campaign, use the Get function.

Take the Quests service for example.

For this service, Get requires a campaign ID and quest ID.

qst, err := c.Quests.Get(cmpID, qstID)

The result is stored in qst of type Quest.

To retrieve a list of a campaign's entities of a certain type, use the Index function.

Take Locations for example.

For this service, Index requires only a campaign ID.

locs, err := c.Locations.Index(cmpID, nil)

If you want to limit the results to only the locations that have been updated since a specific time, provide that time to the Index function.

t := time.Date(2019, time.November, 4, 11, 0, 0, 0, time.UTC)

locs, err := c.Locations.Index(cmpID, t)

The result is stored in locs of type []Location.

To create a new entity, use the Create function.

Take Characters for example.

For this service, Create requires a campaign ID and the data for the new character in the form of type SimpleCharacter.

ch := SimpleCharacter{
    Name: "Daenerys Targaryen",
    Sex: "Female",
    Title: "Mother of Dragons",
}

_, err := c.Characters.Create(cmpID, ch)

The Create functions return the newly created entity back to the caller.

This example simply discards the value.

To update an existing entity, use the Update function.

Take Items for example.

For this service, Update requires a campaign ID, an item ID, and the data for the new item in the form of type SimpleItem.

item := SimpleItem{
    Name: "Bag of Holding",
    Size: "15 pounds",
    Price: "300 gold",
}

_, err := c.Items.Update(cmpID, item)

The Update functions return the updated entity back to the caller.

This example simply discards the value.

To delete an entity, use the Delete function.

Take Journals for example.

For this service, Delete requires a campaign ID and a journal ID.

err := c.Journals.Delete(cmpID, jrnID)

The Kanka API is rate limited. For the most accurate and updated information, please visit the Kanka documentation.

If one of your requests to the Kanka API fails due to the rate limit or other temporary reason, the error returned can be asserted for the Temporary behavior.

For more information about temporary errors, please visit Dave Cheney's blog.

If you would like to contribute to this project, please adhere to the following guidelines.

• Submit an issue describing the problem.
• Fork the repo and add your contribution.
• Add appropriate tests.
• Run go fmt, go vet, and golint.
• Prefer idiomatic Go over non-idiomatic code.
• Follow the basic Go conventions found here.
• If in doubt, try to match your code to the current codebase.
• Create a pull request with a description of your changes.