wallabago

README

wallabago

Go wrapper library for the Wallabag API

Links

• http://wallabag.org/
• https://github.com/wallabag/wallabag/
• https://doc.wallabag.org/en/developer/api/readme.html
• https://app.wallabag.it/api/doc

Project Status

Currently supported wallabag version

• wallago version 1.0.0 and before: compatible with wallabag 2.2.1 - 2.2.3
• wallago version 2.0.0: tested only with wallabag 2.3.2
• wallago version 4.0.0 until 5.1.0: tested only with wallabag 2.3.8
• wallago version 6.0.0 until latest version: tested only with wallabag 2.4.0

Travis CI

Go Report Card

Status of the implementation of the API calls

GET

• GET /api/annotations/{entry}.{_format}
• GET /api/entries.{_format}
• GET /api/entries/exists.{_format}
• GET /api/entries/{entry}.{_format}
• GET /api/entries/{entry}/export.{_format}
• GET /api/entries/{entry}/tags.{_format}
• GET /api/tags.{_format}
• GET /api/version.{_format}

POST

• POST /api/annotations/{entry}.{_format}
• POST /api/entries.{_format}
• POST /api/entries/{entry}/tags.{_format}

PUT

• PUT /api/annotations/{annotation}.{_format}

DELETE

• DELETE /api/annotations/{annotation}.{_format}
• DELETE /api/entries/{entry}.{_format}
• DELETE /api/entries/{entry}/tags/{tag}.{_format}
• DELETE /api/tag/label.{_format}
• DELETE /api/tags/label.{_format}
• DELETE /api/tags/{tag}.{_format}

PATCH

• PATCH /api/entries/{entry}.{_format}
• PATCH /api/entries/{entry}/reload.{_format}

Projects using wallabago

• wallabako - wallabag client for Kobo readers
• wallabag-stats - draws a chart for unread and total articles in your wallabag instance
• wallabag-add-article - commandline utility to add an article to wallabag

Documentation

Index

• Constants
• func APICall(apiURL string, httpMethod string, postData []byte) ([]byte, error)
• func AddEntryTags(entry int, tags ...string) error
• func DeleteEntryTag(entry int, tag int) error
• func ExportEntry(bodyByteGetterFunc BodyByteGetter, articleID int, format string) ([]byte, error)
• func GetAuthTokenHeader() (string, error)
• func GetEntriesExists(bodyByteGetterFunc BodyByteGetter, urls []string) (map[string]bool, error)
• func GetNumberOfArchivedArticles() (int, error)
• func GetNumberOfStarredArticles() (int, error)
• func GetNumberOfTotalArticles() (int, error)
• func PostEntry(url, title, tags string, starred, archive int) error
• func ReadConfig(configJSON string) (err error)
• func SetConfig(wbgConfig WallabagConfig)
• func Version(bodyStringGetterFunc BodyStringGetter) (string, error)
• type Annotation
• type Annotations
  • func GetAnnotations(bodyByteGetterFunc BodyByteGetter, articleID int) (Annotations, error)
• type BodyByteGetter
• type BodyStringGetter
• type Embedded
• type Entries
  • func GetEntries(bodyByteGetterFunc BodyByteGetter, archive int, starred int, sort string, ...) (Entries, error)
• type Item
  • func GetAllEntries() ([]Item, error)
  • func GetEntry(bodyByteGetterFunc BodyByteGetter, articleID int) (Item, error)
• type Link
• type Links
• type Range
• type Tag
  • func GetTags(bodyByteGetterFunc BodyByteGetter) ([]Tag, error)
  • func GetTagsOfEntry(bodyByteGetterFunc BodyByteGetter, articleID int) ([]Tag, error)
• type Token
• type WallabagConfig
  • func NewWallabagConfig(wallabagURL, clientID, clientSecret, userName, userPassword string) WallabagConfig
• type WallabagTime
  • func (t *WallabagTime) UnmarshalJSON(buf []byte) (err error)

Constants

const WallabagTimeLayout = "2006-01-02T15:04:05-0700"

WallabagTimeLayout is a variation of RFC3339 but without colons in the timezone delimeter, breaking the RFC

Functions

func APICall

func APICall(apiURL string, httpMethod string, postData []byte) ([]byte, error)

APICall authenticates to wallabag instane before issuing the HTTP request

func AddEntryTags

func AddEntryTags(entry int, tags ...string) error

AddEntryTags add tags to an entry

func DeleteEntryTag

func DeleteEntryTag(entry int, tag int) error

DeleteEntryTag removes a tag from an entry

func ExportEntry

func ExportEntry(bodyByteGetterFunc BodyByteGetter, articleID int, format string) ([]byte, error)

ExportEntry queries the API to retrieve a single entry in a predefined format according to the API request /entries/ID/export.FORMAT

func GetAuthTokenHeader

func GetAuthTokenHeader() (string, error)

GetAuthTokenHeader will make sure there's a working token and return a valid string to be used as an Authentication: header

func GetEntriesExists

func GetEntriesExists(bodyByteGetterFunc BodyByteGetter, urls []string) (map[string]bool, error)

GetEntriesExists queries the API for articles according to the API request /entries/exists it checks if the urls in the given array exist returns a map with the URL as key and the result as value

func GetNumberOfArchivedArticles

func GetNumberOfArchivedArticles() (int, error)

GetNumberOfArchivedArticles returns the number of archived articles in wallabag

func GetNumberOfStarredArticles

func GetNumberOfStarredArticles() (int, error)

GetNumberOfStarredArticles returns the number of starred articles in wallabag (including unread and archived starred ones)

func GetNumberOfTotalArticles

func GetNumberOfTotalArticles() (int, error)

GetNumberOfTotalArticles returns the number of all articles saved in wallabag

func PostEntry

func PostEntry(url, title, tags string, starred, archive int) error

PostEntry creates a new article in wallabag

func ReadConfig

func ReadConfig(configJSON string) (err error)

ReadConfig will read the configuration from the given configJSON file and set the global Config setting with the results of the parsing

func SetConfig

func SetConfig(wbgConfig WallabagConfig)

SetConfig sets global wallabago Config

func Version

func Version(bodyStringGetterFunc BodyStringGetter) (string, error)

Version returns the version of the configured wallabag instance

Types

type Annotation

type Annotation struct {
	AnnotatorSchemaVersion string       `json:"annotator_schema_version"`
	CreatedAt              WallabagTime `json:"created_at"`
	ID                     int          `json:"id"`
	Quote                  string       `json:"quote"`
	Ranges                 []Range      `json:"ranges"`
	Text                   string       `json:"text"`
	UpdatedAt              WallabagTime `json:"updated_at"`
}

Annotation represents one annotation made to an article

type Annotations

type Annotations struct {
	Rows  []Annotation `json:"rows"`
	Total int          `json:"total"`
}

Annotations represents an annotation result API call for an article

func GetAnnotations

func GetAnnotations(bodyByteGetterFunc BodyByteGetter, articleID int) (Annotations, error)

GetAnnotations queries the API for all annotations of an article according to /api/annotations/ID

type BodyByteGetter

type BodyByteGetter func(url string, httpMethod string, postData []byte) ([]byte, error)

BodyByteGetter represents a function returning the body of an HTTP response as byte array

type BodyStringGetter

type BodyStringGetter func(url string, httpMethod string, postData []byte) (string, error)

BodyStringGetter represents a function returning the body of an HTTP response as string

type Embedded

type Embedded struct {
	Items []Item `json:"items"`
}

Embedded items in the API request

type Entries

type Entries struct {
	Page      int
	Limit     int
	Pages     int
	Total     int
	NaviLinks Links    `json:"_links"`
	Embedded  Embedded `json:"_embedded"`
}

Entries represents the object being returned from the API request /entries

func GetEntries

func GetEntries(bodyByteGetterFunc BodyByteGetter, archive int, starred int, sort string, order string, page int, perPage int, tags string) (Entries, error)

GetEntries queries the API for articles according to the API request /entries

type Item

type Item struct {
	Links          Links        `json:"_links"`
	Annotations    []Annotation `json:"annotations"`
	ArchivedAt     WallabagTime `json:"archived_at"`
	CreatedAt      WallabagTime `json:"created_at"`
	Content        string       `json:"content"`
	DomainName     string       `json:"domain_name"`
	GivenURL       string       `json:"given_url"`
	HashedGivenURL string       `json:"hashed_given_url"`
	HashedURL      string       `json:"hashed_url"`
	ID             int          `json:"id"`
	IsArchived     int          `json:"is_archived"`
	IsPublic       bool         `json:"is_public"`
	IsStarred      int          `json:"is_starred"`
	Language       string       `json:"language"`
	Mimetype       string       `json:"mimetype"`
	OriginURL      string       `json:"origin_url"`
	PreviewPicture string       `json:"preview_picture"`
	PublishedAt    WallabagTime `json:"published_at"`
	PublishedBy    []string     `json:"published_by"`
	ReadingTime    int          `json:"reading_time"`
	StarredAt      WallabagTime `json:"starred_at"`
	Tags           []Tag        `json:"tags"`
	Title          string       `json:"title"`
	UID            string       `json:"uid"`
	UpdatedAt      WallabagTime `json:"updated_at"`
	URL            string       `json:"url"`
	UserEmail      string       `json:"user_email"`
	UserID         int          `json:"user_id"`
	UserName       string       `json:"user_name"`
}

Item represents individual items in API responses

func GetAllEntries

func GetAllEntries() ([]Item, error)

GetAllEntries calls GetEntries with no parameters, thus using the default values of the API request /entries and returning all articles as []wallabago.Item

func GetEntry

func GetEntry(bodyByteGetterFunc BodyByteGetter, articleID int) (Item, error)

GetEntry queries the API for a specific article according to the API request /entries/ID

type Link

type Link struct {
	Href string
}

Link object consists of its URL

type Links

type Links struct {
	Self  *Link
	First *Link
	Last  *Link
	Next  *Link
}

Links contains four links (self, first, last, next), being part of the Entries object

type Range

type Range struct {
	End         string      `json:"end"`
	EndOffset   interface{} `json:"endOffset"`
	Start       string      `json:"start"`
	StartOffset interface{} `json:"startOffset"`
}

Range represents the text borders of an annotation

type Tag

type Tag struct {
	ID    int    `json:"id"`
	Label string `json:"label"`
	Slug  string `json:"slug"`
}

Tag represents one tag with its properties

func GetTags

func GetTags(bodyByteGetterFunc BodyByteGetter) ([]Tag, error)

GetTags queries the API for all tags in wallabag /tags

func GetTagsOfEntry

func GetTagsOfEntry(bodyByteGetterFunc BodyByteGetter, articleID int) ([]Tag, error)

GetTagsOfEntry queries the API for the tags of an article /entries/ID

type Token

type Token struct {
	AccessToken    string
	ExpirationTime time.Time
	TokenType      string
	Scope          string
	RefreshToken   string
}

Token represents the object being returned from the oauth process at the API containing the access token, expire time (after converting it from the number of seconds the token is valid to the point in time where it will expires), type of token, scope and a refresh token

type WallabagConfig

type WallabagConfig struct {
	WallabagURL  string
	ClientID     string
	ClientSecret string
	UserName     string
	UserPassword string
}

WallabagConfig contains all data needed to connect to wallabag API like URL, id and secret of the API client and user name and according password

var Config WallabagConfig

Config containing all data to access wallabag API

func NewWallabagConfig

func NewWallabagConfig(wallabagURL, clientID, clientSecret, userName, userPassword string) WallabagConfig

NewWallabagConfig initializes a new WallabagConfig

type WallabagTime

type WallabagTime struct {
	time.Time
}

WallabagTime overrides builtin time to allow for custom time parsing

func (*WallabagTime) UnmarshalJSON

func (t *WallabagTime) UnmarshalJSON(buf []byte) (err error)

UnmarshalJSON parses the custom date format wallabag returns