Bookmark

Instapaper's bookmark API

Read more at the official Instapaper API docs page

Operations

List

svc := instapaper.BookmarkService{
			Client: apiClient,
		}
		bookmarkList, err := svc.List(instapaper.BookmarkListRequestParams{
			Limit: 5,
		})

This returns a BookmarkListResponse instance:

type BookmarkListResponse struct {
	Bookmarks   []Bookmark
	Highlights  []Highlight
	RawResponse string
}

The RawResponse field contanins the unmodified response from Instapaper in case you want to decode it yourself or debug what's happening. You can use a BookmarkListRequestParams instance to define what you want returned:

type BookmarkListRequestParams struct {
	Limit           int
	Skip            []Bookmark
	CustomHaveParam string
	Folder          string
}

Limit is the maximum number of bookmarks the API should return - the maximum is 500.

You can optionally pass a slice of bookmarks for Skip so the response won't contain them. Instapaper has a more intricate way of filtering out bookmarks, so you can pass your custom filtering string with CustomHaveParam - if this field is not empty, Skip will not be passed in the API call. The weird name is related to how it's called in the API itself. Read more at the official Instapaper API docs page

Finally, you can get bookmarks from a specific folder by filling out the Folder parameter.

There's also a default set of parameters defined: DefaultBookmarkListRequestParams - this does no filtering and maxes out the number of returned items to 500.

GetText

Returns the specified bookmark's processed text-view HTML, which is always text/html encoded as UTF-8.

txt, err := svc.GetText(bookmarkList.Bookmarks[0].ID)

Star and Unstar

Stars or un-stars the specific bookmark

err := svc.Star(bookmarkList.Bookmarks[0].ID)
err = svc.UnStar(bookmarkList.Bookmarks[0].ID)

Archive and UnArchive

Archives or un-archives the specific bookmark

err := svc.Archive(bookmarkList.Bookmarks[0].ID)
err = svc.UnArchive(bookmarkList.Bookmarks[0].ID)

DeletePermanently

WARNING this permanently deletes the specific bookmark!!!

err := svc.DeletePermanently(bookmarkList.Bookmarks[0].ID)

Move

Moves the bookmark to a specific folder

err := svc.Move(bookmarkList.Bookmarks[0].ID, instapaper.FolderIDArchive) // equivalent to archiving in this case
err = svc.Move(bookmarkList.Bookmarks[0].ID, "12345") // Folder IDs are strings. I know, weird API :)

UpdateReadProgress

Updates the read progress percentage on a specific bookmark

err := svc.UpdateReadProgress(bookmarkList.Bookmarks[0].ID, 0.5, 0)

The first parameter is a float32 between 0.0 and 1.0 representing the read progress percentage.

The second parameter is an optional Unix timestamp of when the update happened. If 0 is given, the current Unix timestamp is passed to the API call.

Add

Adds a new bookmark, either from a URL or from a supplied piece of content. Refer to the official API description for a more detailed explanation.

The parameter structure looks like this:

type BookmarkAddRequestParams struct {
	URL               string
	Title             string
	Description       string
	Folder            string
	ResolveFinalURL   bool
	Content           string
	PrivateSourceName string
}

Basically, either a URL or Content or a (Content, PrivateSourceName) pair is required.

• Title - An optional title. If not supplied it'll be parsed from the content (either the one supplied or the one fetched on the URL)
• Description - An optional Description. If not supplied it'll be parsed from the content (either the one supplied or the one fetched on the URL)
• Folder - An optional folder to put the bookmark in. If not supplied, it gets added to the default 'unread' folder.
• ResolveFinalURL - You can set it to false if you know for sure that the URL is the final one, not shortened, redirected. If not specified the API will try to follow redirects to resolve the final URL.
• Content - The (html/plaintext) content can be optionally supplied. Useful for content behind login, paywalls etc. Required when supplying PrivateSourceName
• PrivateSourceName - When specified, the URL is completely ignored. Requires Content to be specified. Used for adding non-fetchable content, e.g. emails

This is a sync operation, returning the newly created bookmark.

bookmark, err := svc.Add(instapaper.BookmarkAddRequestParams{
    Title:             "YOLO TITLE",
    Content:           "YOLO",
    PrivateSourceName: "None of your business pal ;)",
})

bookmark, err = svc.Add(instapaper.BookmarkAddRequestParams{
    URL:             "https://golang.org/",
})