justin (JustGiving Interface) 
justin is a Go library providing a higher-level wrapper around the JustGiving API
Overview
justin provides some higher-level functionality to the JustGiving API and is intended to speed up development of server-to-server interactions such as writing a micro service to interact with JustGiving.
The JustGiving API has a simple authentication model, all that is required is an API key.
Some API methods require user account authentication which is facilitated through a Basic Authentication header, justin will not store any user credentials so these API methods will simply have user name and password as part of their method signature.
Validation
justin tries not to stand in the way of what you might want to send to JustGiving via their API and does not perform any validation prior to sending a request. However justin does like to try and be helpful. If a request fails, validation will then be run to augment the standard error message. The validation methods are also available on both the models and justin.Service for you to use if you wish.
Running the tests
Set a JUSTIN_APIKEY env. var. to the API key to use for testing
Set a JUSTIN_USER env. var. to the email and password of the user account to use for testing (in user:password format)
Set a JUSTIN_CHARITY env. var. to the charity id to use for testing
Set a JUSTIN_EVENT env. var. to the event id to use for testing
Including account admin tests
go test -v -acc using the -acc flag will create an account for the user as set through the env. vars. and send an email reminder to the newly created account
e.g. to just create an account and check it worked run go test -v -acc -run="TestAccountAvailabilityCheck"
Standard tests
go test -v expects the user account set through the env. vars. to already exist
Getting Started
Creating the service:
// Generated API Key accessible through a JustGiving developer account
apiKey := "abc12345"
// Timeout for the API requests
timeout := time.Duration(20) * time.Second
// JustGiving Environment to use
env := justin.Sandbox
svc, err := justin.CreateWithAPIKey(justin.APIKeyContext{
APIKey: apiKey, Env: env, Timeout: timeout,
})
if err != nil {
// ...
}
// Optionally a logger can be specified to log raw http requests/responses
//()
var logger api.LoggerFunc
logger = func(m string) (err error) {
fmt.Printf("[%v] %s", time.Now(), m))
return nil
}
svcWithLogger, err := justin.CreateWithAPIKey(justin.APIKeyContext{
APIKey: apiKey, Env: env, Timeout: timeout, HTTPLogger: logger,
})
if err != nil {
// ...
}
// Use svc / svcWithLogger ...AccountAvailabilityCheck
Check the availability of a JustGiving account by email address:
eml, err := mail.ParseAddress("rob@golang.org")
if err != nil {
// ...
}
avail, err = svc.AccountAvailabilityCheck(*eml)Validate
Validate a set of supplied user credentials against the JustGiving database:
eml, err := mail.ParseAddress("rob@golang.org")
if err != nil {
// ...
}
pwd := "goph3r"
valid, err := svc.Validate(*eml, pwd)AccountRegistration
Create a new user account with JustGiving:
eml, err := mail.ParseAddress("john@justgiving.com")
if err != nil {
// ...
}
acc := models.Account{
Title: "Mr",
FirstName: "John",
LastName: "Smith",
Email: *eml,
Password: "S3cr3tP4ssw0rd",
AddressLine1: "Second Floor, Blue Fin Building",
AddressLine2: "110 Southwark Street",
County: "London",
TownOrCity: "London",
Postcode: "SE1 0TA",
Country: "United Kingdom",
}
err = svc.AccountRegistration(acc)RequestPasswordReminder
Sends a password reset email:
eml, err := mail.ParseAddress("rob@golang.org")
if err != nil {
// ...
}
err := svc.RequestPasswordReminder(*eml)FundraisingPageUrlCheck
Checks the availability of a JustGiving fundraising page
pageShortName := "robspage"
avail, suggestions, err := svc.FundraisingPageUrlCheck(pageShortName)
// If the page is not available some alternative page short names
// will be returned as suggestions []stringRegisterFundraisingPage
Registers a Fundraising Page on the JustGiving website
eml, err := mail.ParseAddress("john@justgiving.com")
if err != nil {
// ...
}
pwd := "S3cr3tP4ssw0rd"
var imgs [2]models.Image
url, err := url.Parse("http://images.justgiving.com/image/image1.jpg")
if err != nil {
// ...
}
imgs[0] = models.Image{Caption: "Image 1 Caption", URL: *url}
url, err = url.Parse("http://images.justgiving.com/image/image2.png")
if err != nil {
// ...
}
imgs[1] = models.Image{Caption: "Image 2 Caption", URL: *url}
var cuscodes [6]string
cuscodes[0] = "CUSTOMCODE1"
// Can have up to 6 custom codes...
cuscodes[5] = "CUSTOMCODE6"
pg := models.FundraisingPageForEvent{
CharityID: 123,
EventID: 456789,
PageShortName: "johnstestpage",
PageTitle: "Page Title",
PageStory: "Page Story",
Images: imgs[:],
TargetAmount: "100.00",
CustomCodes: cuscodes,
CurrencyCode: "GBP",
CharityFunded: false,
JustGivingOptIn: false,
CharityOptIn: false,
}
pageURL, signOnURL, err := s.RegisterFundraisingPageForEvent(*eml, pwd, pg)
// You can redirect your users to the returned signOnURL and they will be
// automatically signed in to their newly created fundraising page.
// The URL can only be used once, and must be used within 20 minutes of
// the page being created.Roadmap
Update to use Go modules
Add Team API methods https://api.justgiving.com/docs/resources/v1/Team
