diff --git a/README.md b/README.md index c06aeb7..fcf62dd 100644 --- a/README.md +++ b/README.md @@ -6,27 +6,12 @@ gol (**G**olang **O**pen **L**ibrary) is an interface for the OpenLibrary API. F [![Go Reference](https://pkg.go.dev/badge/github.com/Open-pi/gol.svg)](https://pkg.go.dev/github.com/Open-pi/gol) ![go](https://github.com/Open-pi/gol/actions/workflows/go.yml/badge.svg) -As OpenLibrary's data is always changing, under the hood all the JSON data is handled through `gabs`. Subsequently if a field is not accessible with a method, `gabs`'s container can be used instead from any `struct`. -## Functions -These are the API functions (WorkAPI, EditionAPI, etc) to get the data. With them you can make other calls. - -| Functions | Args | Returns | -|---|---|--| -| GetWork | WorkId | (w Work, err error) | -| GetEdition | OLID | (b Book, err error) | -| GetEditionISBN | ISBN | (b Book, err error) | -| GetCoverURL | coverType, identifierType, identifier, size | string | -| GetBookCoverURL | identifierType, identifier, size | string | -| GetAuthorCoverURL | identifierType, identifier, size | string | -| GetAuthor | Author Id | (a Author) | -| GetSubject | string | Subject | -| GetSubjectDetails | string | Subject | -| Search | search URL | SearchData | -| Query | Query URL | map[string]interface{} | +As OpenLibrary's data is always changing, under the hood all the JSON data is handled through [\`gabs\`](https://github.com/Jeffail/gabs/). Subsequently if a field is not accessible with a method, `gabs`'s container can be used instead from any `struct`. +## Functions For more information, browse the `docs` folder where you can find additional about every API and its subsequent methods. -* [WorkAPI](docs/WorkAPI.md) -* [BookAPI](docs/BookAPI.md) -* [CoverAPI](docs/CoverAPI.md) -* [AuthorAPI](docs/AuthorAPI.md) -* [SearchAPI](docs/SearchAPI.md) +* [Work API](docs/WorkAPI.md) +* [Book API](docs/BookAPI.md) +* [Cover API](docs/CoverAPI.md) +* [Author API](docs/AuthorAPI.md) +* [Subject/Search/Query API](docs/SearchAPI.md) diff --git a/docs/AuthorAPI.md b/docs/AuthorAPI.md index f87aafb..b8d5f18 100644 --- a/docs/AuthorAPI.md +++ b/docs/AuthorAPI.md @@ -1,4 +1,3 @@ -# Depricated! (needs updating) # AuthorAPI The AuthorAPI deals with everything related to Author pages on Open Library that begin with the URL prefix `/authors`. @@ -10,21 +9,17 @@ In these docs you will find all the methods of the `Author` struct. To populate The fields can be found [here](https://pkg.go.dev/github.com/Open-pi/gol#Author) Author satisfy these interfaces: -* Coverer +* HasCovers +* IKeyAuthors ### AuthorAPI Examples Here are some examples of how you could use the AuthorAPI. ```go - author := gol.GetAuthor("OL236174A") // Get the Author Richard Dawkins + + author := gol.GetAuthor("OL236174A") // Get the Author Richard Dawkins // Output: - // gol.Author { - // Bio: gol.Bio{Type: "/type/text", Value: "Clinton Richard Dawkins, FRS, FRSL is a British ethologist, evolutionary biologist and popular science author..."}, - // Name: "Richard Dawkins", - // Title: "FRS, FRSL", - // PersonalName: "Richard Dawkins", - // .... - // } + // Author works := author.Works() // Get the Works of the author // Output: @@ -33,5 +28,5 @@ Here are some examples of how you could use the AuthorAPI. // Get the Author's Photo cover := author.Cover("L") // Alternatively: Cover(author, size) // Output: - // string + // url to the cover ``` \ No newline at end of file diff --git a/docs/BookAPI.md b/docs/BookAPI.md index 3c3769b..fc7ab85 100644 --- a/docs/BookAPI.md +++ b/docs/BookAPI.md @@ -1,4 +1,3 @@ -# Depricated! (needs updating) # Book/EditionAPI Here you can find all the information on how to get Books and what methods the `Book` struct has. @@ -6,42 +5,38 @@ Here you can find all the information on how to get Books and what methods the ` In these examples you will find the most useful methods/function, for more low level on Book structs you can look at the documentation. ```go - book := gol.GetEdition("OL4554174M") // Get the edition using the openlibrary ID + book, err := gol.GetEdition("OL4554174M") // Get the edition using the openlibrary ID // Output: - // gol.Book{ - // Publishers: []string{"Oxford University Press"}, - // ... - // Key: "/books/OL4554174M", - // Authors: []gol.Author{{"/authors/OL236174A"}}, - // ... - // Subjects: []string{"Genetics.", "Evolution (Biology)"}, - // ... - // Title: "The selfish gene", - // ... - // NumberOfPages: 224, - // Languages: []gol.Languages{{"/languages/eng"}}, - // ... - // Isbn10: []string{"0195200004"}, - // ... - // OclcNumbers: []string{"3167790"}, - // Works: []gol.Works{{"/works/OL1966513W"}}, - // ... - // Created: gol.Time{Type: "/type/datetime", Value: "2008-04-01T03:28:50.625462"}, - // LastModified: gol.Time{Type: "/type/datetime", Value: "2021-03-03T05:21:06.382367"}, - // } + // Book, error - book := gol.GetEditionISBN("978-3-16-148410-0") // Get the edition from the ISBN key + book, err := gol.GetEditionISBN("978-3-16-148410-0") // Get the edition from the ISBN key // Output: - // gol.Book{ - // ... - // } + // Book, error + // To load "all" information from the JSON data in the struct + book.Load() + // Returns all the information of the book's authors - authors := book.Authors() // Alternatively you can use Authors(book) + + // Get the keys/ids of the book's author + keyauthors, err := book.KeyAuthors() + + // Get the Authors of the book + authors, err := book.Authors() // Alternatively you can use Authors(book) // Output: - // []Author + // []Author, error - cover := book.Cover("S") // Returns the URL of the book's cover (size Small) + // To get the cover keys/ids of the book + keys, err := book.KeyCovers() + // Output: + // []String, error + + // To get the first (index 0) cover of the book + key := book.FirstCoverKey() // Output: // string + + cover := book.Cover("S") // Returns the URL of the book's cover (size Small) + // Output: + // url ``` \ No newline at end of file diff --git a/docs/CoverAPI.md b/docs/CoverAPI.md index 63c52fb..fc0f5e1 100644 --- a/docs/CoverAPI.md +++ b/docs/CoverAPI.md @@ -1,4 +1,3 @@ -# Depricated! (needs updating) # CoverAPI This part of the library returns the urls covers of authors and books. This is mainly a "low level function" as it's easier to call, for example [`work.Cover()`](WorkAPI.md) to get the url cover of a certain work. diff --git a/docs/SearchAPI.md b/docs/SearchAPI.md index dc71fb2..0ccb9e6 100644 --- a/docs/SearchAPI.md +++ b/docs/SearchAPI.md @@ -1,11 +1,17 @@ -# Depricated! (needs updating) # SearchAPI This section will have all things related to searching and querying the OpenLibrary API. ## SubjectAPI -To start searching for a subject, you use `GetSubject`; which will return a `Subject` struct type. For a more detailed search on subject, you could use `GetSubjectDetails`. +To start searching for a subject, you use `GetSubject`; which will return a `Subject` struct type. For a more detailed search on subject, you can use `GetSubjectDetails`. ### Examples -*Coming soon* +```go + // To search for a subject + sbj, err := GetSubject("Biology") + + // To get a detailed subject + detailed, err := GetSubjectDetails("Biology") +``` + ## SearchAPI When searching you are able to specify which data you are looking for (author, subject, title, etc.) as specified by the OpenLibrary API. Firstly, you have to construct the SearchURL, using `SearchURL` struct type and methods, that would be fed to `Search`. ### Examples diff --git a/docs/WorkAPI.md b/docs/WorkAPI.md index 3ad54dd..9737d9e 100644 --- a/docs/WorkAPI.md +++ b/docs/WorkAPI.md @@ -1,31 +1,36 @@ -# Depricated! (needs updating) # WorkAPI This is the documentation page related to Work pages on Open Library that begin with the URL prefix "/works". You will find here all the operations you can do on works through the `Work` struct. -In it's simplest form, `GetWork` will fetch all the data and returns a filled `Work` struct. And from the struct you can make other calls to get Editions, Authors, and Covers etc. +In it's simplest form, `GetWork` will fetch all the data and returns a filled* `Work` struct. And from the struct you can make other calls to get Editions, Authors, and Covers etc. + +\* filling the struct requires using the Load() method; When using `GetWork()`, `Load()` is called. ### List of methods | Methods | Args | Returns | |---|---|--| | GetWork | WorkId | (w Work, err error) | +| (w *Work) Load | | | +| (w *Work) Key | | string, error | +| (w *Work) Desc | | string, error | +| (w *Work) Subjects | | string, error | +| (w *Work) Title | | string, error | +| (w *Work) KeyAuthors | | []string, error | +| (w *Work) KeyCovers | | []string, error | +|---|---|--| +| (w Work) FirstCoverKey | | string | | (w Work) Cover | size | URL of cover | | (w Work) Authors | | []Authors, err | | (w Work) Editions | | []Book, err | ### WorkAPI Examples ```go - work := gol.GetWork("OL45583W") + work, err:= gol.GetWork("OL45583W") // Output: - // gol.Work{ - // Created: gol.Time{Type: "/type/datetime", Value: "2009-10-15T11:23:34.130855"}, - // Subjects: []string{"History and criticism", "Russian literature", "Russian literature, history and criticism"}, - // LatestRevision: 4, - // Key: "/works/OL45583W", - // Title: "An outline of Russian literature", - // Authors: []gol.AuthorAndType{{gol.Type{"/type/author_role"}, gol.Author{"/authors/OL18295A"}}}, - // ... - // } + // Work, error + + // To get fields + title, err := work.Title() cover := work.Cover("L") // Get a large cover of the work // Output: @@ -33,9 +38,9 @@ In it's simplest form, `GetWork` will fetch all the data and returns a filled `W authors, err := work.Authors() // Get the list of authors that contributed to the work. // Output: - // []Authors + // []Authors, error editions, err := work.Editions() // Get the list of editions liked to the work. // Output: - // []Book + // []Book, error ``` diff --git a/editions.go b/editions.go index 0be0815..e3670e4 100644 --- a/editions.go +++ b/editions.go @@ -74,11 +74,9 @@ func (b *Book) KeyAuthors() ([]string, error) { return b.keyAuthors, nil } -//TODO: add this after dealing with authors API -// Authors returns all the information related to the book's authors -//func (b Book) Authors() (a []Author, err error) { -//return Authors(b) -//} +func (b Book) Authors() ([]Author, error) { + return Authors(&b) +} // KeyCover returns (if it exists) the ID of the work's cover func (b *Book) KeyCovers() ([]string, error) {