LOTR SDK README

About

This is a Go SDK wrapper for the "The One API", a Lord of the Rings HTTP REST data service.

Once signed up for a free account with the-one-api.dev, you can query for trivia like book titles, movie ratings, character stats and famous quotes, using a simple Go interface.

Install

Usage

Taken from example.go, here is an example request for all of the books, limiting to 3 results.

api_key := "" // no api_key required for the /books endpoint
apiClient := NewLotrSdkClient(api_key)
apiResult, err := apiClient.GetBooks().Limit(3).Send()
if err != nil {
    log.Fatal(err)
}

json, err := json.MarshalIndent(apiResult, "", "  ")
if err != nil {
    log.Fatal(err)
}

fmt.Println(string(json))
// Console output (Prettified JSON string representation):
// {
//   "docs": [
//     {
//       "_id": "5cf5805fb53e011a64671582",
//       "name": "The Fellowship Of The Ring"
//     },
//     {
//       "_id": "5cf58077b53e011a64671583",
//       "name": "The Two Towers"
//     },
//     {
//       "_id": "5cf58080b53e011a64671584",
//       "name": "The Return Of The King"
//     }
//   ],
//   "limit": 3,
//   "offset": 0,
//   "page": 1,
//   "pages": 1,
//   "total": 3
// }

First, an apiClient needs to be initialized with your authentication key. This step is performed once, and the client is used for the rest your program duration.

api_key := "my_api_key"
apiClient := NewLotrSdkClient(api_key)

Requests are made as methods on the apiClient object. The following requests are available:

GetBooks()
GetBook(bookId string)
GetBookChapters(bookId string)

GetChapters()
GetChapter(chapterId string)

GetCharacters()
GetCharacter(characterId string)
GetCharacterQuotes(characterId string)

GetMovies()
GetMovie(movieId string)
GetMovieQuotes(movieId string)

GetQuotes()
GetQuote(quoteId string)

Rather than provide an options object for query parameters, this SDK utilizes a more functional-inspired approach, where modifier functions are chained to the request. The following modifiers are available, and can be chained in any quantity and order:

Limit(limit int)
Page(page int)
Offset(offset int)
SortFieldAscending(field string)
SortFieldDescending(field string)
WithField(field string)
WithFieldValue(field string, value string)
WithFieldValueLike(field string, value string)
WithFieldValueUnlike(field string, value string)
WithoutFieldValue(field string, value string)
WithFieldValueGreaterThan(field string, value string)
WithFieldValueLessThan(field string, value string)
WithFieldValueGreaterThanOrEqual(field string, value string)
WithFieldValueLessThanOrEqual(field string, value string)
WithFieldValues(field string, values []string)
WithoutFieldValues(field string, values []string)

To issue the request, invoke the Send() method at the end of the chain of zero or more modifiers.

apiResult, err := apiClient.GetBooks().Limit(3).Send()

The result will be a Go struct that mirrors the JSON response from the server. The response provides information about the requested entry Limit, Page count, Offset index, and Total entries, which can be used to craft requests appropriate to your pagination needs. The Docs property is an array of typed entries, depending on the resource that was queried. Here is the struct of the Response wrapper and the Book entry.

type LotrSdkResponse[T any] struct {
	Docs   []T   `json:"docs"`
	Limit  int32 `json:"limit"`
	Offset int32 `json:"offset"`
	Page   int32 `json:"page"`
	Pages  int32 `json:"pages"`
	Total  int32 `json:"total"`
}

type LotrSdkBook struct {
	Id   string `json:"_id"`
	Name string `json:"name"`
}

A note on naming convention and modifier usage. The Go object fields all start with a capital letter, as is required for exported fields, while the JSON fields all start with lower-case or an underscore. The JSON library utilizes the json tag on the Go struct fields to know how to do this conversion.

When using the modifiers, the strings passed as parameters should match the case used in the JSON. So, the field Name should be passed to the modifier function as the string name. A future improvement to this SDK would be to provide const tokens that can be used in place of strings.

Test

Each api file has an associated set of unit tests. HTTP requests are mocked for the tests. In order to run the unit tests, issue the following command in a console:

$ go test ./src