chatterino/api

API powering some Chatterino2 features

API

Go web service that serves as a cache to APIs that each Chatterino client could use.

Routes

Resolve URL

link_resolver/:url
Resolves a url into a preview tooltip.
Route content type: application/json
Route HTTP Status Code is almost always 200 as long as we were able to generate information about the URL, even if the API we call returns 404 or 500.
If the given URL is not a valid url, the Route HTTP status code will be 400.

Examples

url parameter: https://example.com/page

{
  "status": 200,                                               // status code returned or inferred from the page
  "thumbnail": "http://api.url/thumbnail/web.com%2Fimage.png", // proxied thumbnail url if there's an image
  "message": "",                                               // used to forward errors in case the website e.g. couldn't load
  "tooltip": "<div>tooltip</div>",                             // HTML tooltip used in Chatterino
  "link": "http://example.com/longer-page"                     // final url, after any redirects
}

url parameter: https://example.com/error

{
  "status": 404,
  "message": "Page not found"
}

API Uptime

health/uptime
Returns API service's uptime. Example response:

928h2m53.795354922s

API Memory usage

health/memory
Returns information about memory usage. Example response:

Alloc=505 MiB, TotalAlloc=17418866 MiB, Sys=3070 MiB, NumGC=111245

API Uptime and memory usage

health/combined
Returns both uptime and information about memory usage. Example response:

Uptime: 928h5m7.937821282s - Memory: Alloc=510 MiB, TotalAlloc=17419213 MiB, Sys=3070 MiB, NumGC=111246

Using your self-hosted version

If you host your own version of this API, you can modify which url Chatterino2 uses to resolve links and to resolve twitch emote sets.
Change link resolver
Change Twitch emote resolver
How to build and host
Running in Docker

api's Issues

Migrate to Twitter API v2

The documentation now recommends for new projects to use the v2 API. Chatterino currently uses v1. Quoting from their website:

Twitter API v2 is ready for prime time! We recommend that the majority of developers start to think about migrating to v2 of the API, and for any new users to get started with v2.

Add video creation date to youtube links

I think that youtube's api provides that info, so it would be neat to have video creation next to data the rest of tooltip data.

Including comment count sounds like an option as well, but I don't know if that wouldn't be too much data for a tooltip already.

Add an option to customize the limit that images are fetched

Currently the limit is 5MB, what if I wanted to make it 10 or 15MB?

`type` field in the twitchemotes resolver is empty and unnecessary

In twitchemtoes resolver, field type is not / no longer returned in twitchemotes' API, as far as I investigated in chatterino's source code, that field is present in the Emote struct, but not utilized in any way. I suggest we simply remove it.
Example response: https://braize.pajlada.com/chatterino/twitchemotes/set/302023435/

Youtube Channel support

What service do you want support added for?

Can we add support for Youtube channel links?

Links

https://youtube.com/nymnion
https://www.youtube.com/c/nymnion
https://www.youtube.com/channel/UC9cv7H0DDQU8Zt5n2igzp0Q
https://www.youtube.com/user/rossmanngroup
https://www.youtube.com/c/grindinggear

Thumbnail

Youtube channel profile image
Channel description?
Subscribers count?

Additional information

https://support.google.com/youtube/answer/6180214

Thumbnail Error Responses are 200 OK and `text/plain`

Animated webp links aren't resolved, so requesting the thumbnail for such link will result in an error. However, the HTTP status code of the response is 200 OK (even though the response says 404). Furthermore, the content-type is text/plain but it's clear that JSON is returned.

Example link:
https://braize.pajlada.com/chatterino/thumbnail/https%3A%2F%2Fcdn.7tv.app%2Femote%2F60afbfbaa3648f409a6e5211%2F4x

YouTube clip support

What service do you want support added for?
YouTube clips

Links

From what I can tell it's just the one link format for now:

1. https://youtube.com/clip/Ugx1Pkw2r6TFJIIDXwx4AaABCQ
2. https://youtube.com/clip/Ugz4YHQPS1pC2ngk0ed4AaABCQ

Thumbnail

Same as the YT video thumbnails.

Additional information

Haven't looked into the API support for this, might be sitting here for a bit.

Add thumbnails for twitch sub emotes

Hovering on a twitch emotes emote link would show a thumbnail of the sub emote, the emote name and the channel: https://twitchemotes.com/

Add Helix API endpoints for anonymous users

Anonymous users of Chatterino will not be able to use certain features of Chatterino, if the underlying API is migrated to the Twitch Helix API: Chatterino/chatterino2#1915

Chatterino currently uses these methods: https://github.com/Chatterino/chatterino2/tree/master/src/providers/twitch/api#helix - "get users", "get user follows", "get streams".
And if Chatterino/chatterino2#1928 is implemented, also "get channel" and "get cheeremotes"

The API simply has to provide a forwarder, allowing anybody to make anonymous requests to fetch from these endpoints. The request is then forwarded to Twitch, with an App Access Token used for authentication to be able to access the API.

The modification can then be applied here: https://github.com/Chatterino/chatterino2/blob/c7a2f4cc929681662e3ff0cf7e8d8e2f872039cf/src/providers/twitch/api/Helix.cpp#L335

Add rich responses for Wikipedia links

What service do you want support added for?

Wikipedia

Links

1. https://en.wikipedia.org/wiki/Long_and_short_scales
2. https://en.wikipedia.org/wiki/Rick_Astley

Thumbnail

Of course, the title should be included in the hover popup. However, the main interest is the extract field in the API response from the endpoint linked below.
Additionally, we could also add the thumbnail picture from the API response. (Note that this is not present for every page.)

Additional information

API endpoint: /page/summary/{title}

Example request:

curl -X GET "https://en.wikipedia.org/api/rest_v1/page/summary/Long_and_short_scales?redirect=false"

Example response:

{
  "type": "standard",
  "title": "Long and short scales",
  "displaytitle": "Long and short scales",
  "namespace": {
    "id": 0,
    "text": ""
  },
  "wikibase_item": "Q725503",
  "titles": {
    "canonical": "Long_and_short_scales",
    "normalized": "Long and short scales",
    "display": "Long and short scales"
  },
  "pageid": 949880,
  "lang": "en",
  "dir": "ltr",
  "revision": "998899957",
  "tid": "9bf4dc90-6f73-11eb-a81b-b5fabaa57223",
  "timestamp": "2021-01-07T15:21:12Z",
  "description": "List of countries using one or several different large-number naming systems for integer powers of ten",
  "description_source": "local",
  "content_urls": {
    "desktop": {
      "page": "https://en.wikipedia.org/wiki/Long_and_short_scales",
      "revisions": "https://en.wikipedia.org/wiki/Long_and_short_scales?action=history",
      "edit": "https://en.wikipedia.org/wiki/Long_and_short_scales?action=edit",
      "talk": "https://en.wikipedia.org/wiki/Talk:Long_and_short_scales"
    },
    "mobile": {
      "page": "https://en.m.wikipedia.org/wiki/Long_and_short_scales",
      "revisions": "https://en.m.wikipedia.org/wiki/Special:History/Long_and_short_scales",
      "edit": "https://en.m.wikipedia.org/wiki/Long_and_short_scales?action=edit",
      "talk": "https://en.m.wikipedia.org/wiki/Talk:Long_and_short_scales"
    }
  },
  "extract": "The long and short scales are two of several naming systems for integer powers of ten which use some of the same terms for different magnitudes.",
  "extract_html": "<p>The <b>long</b> and <b>short scales</b> are two of several naming systems for integer powers of ten which use some of the same terms for different magnitudes.</p>"
}

Thumbnails for Twitter links

Currently Twitter links have no extra information. It would be nice to get a preview of the text and potentially the images linked in the tweet.

Here is an example tweet with an image: https://twitter.com/nymnion/status/1273584566826086400
And a plain tweet without anything fancy: https://twitter.com/nymnion/status/1269222603803234304

Prevent YouTube API 403 errors from showing in tooltips

As Chatterino grows, the calls to the YouTube API increase which causes call quotas to be hit more frequently. When a quota is exceeded, the Chatterino API returns a tooltip containing the YouTube HTML error response instead of the preview. Ideally c2api would return a nicer error message (such as "chatterino was unable to get information about this video"), or use an alternative source of data.

Since YouTube supports oEmbed, the thumbnail URL, video title, and channel name can be resolved without an API call. This is enough to present back to the user. An example workflow is below:

get YT preview request:
    call the YT API
    if YT call is success:
        return tooltip using YT data
    
    fetch oEmbed data
    return a slimmed down tooltip with just the thumbnail, title, & channel name

Example YT oEmbed response:

{
  "title": "Rick Astley - Never Gonna Give You Up (Official Music Video)",
  "author_name": "Rick Astley",
  "author_url": "https://www.youtube.com/c/RickastleyCoUkOfficial",
  "type": "video",
  "height": 113,
  "width": 200,
  "version": "1.0",
  "provider_name": "YouTube",
  "provider_url": "https://www.youtube.com/",
  "thumbnail_height": 360,
  "thumbnail_width": 480,
  "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
  "html": ...omitted for brevity...
}

Twitch Profile support

What service do you want support added for?

Add support for twitch.tv profile links

Links

1. https://twitch.tv/pajlada
2. https://www.twitch.tv/forsen
3. https://www.twitch.tv/fourtf

Thumbnail

Profile image
Live status?
Bio?
Followers?

Additional information

https://dev.twitch.tv/

Split Build CI action into separate build and test actions

Currently, both building and testing is being handled within Build action on the CI. I believe this should be split into 2 separate sets of actions to make it more obvious what's going on when, for example, build succeeds, but tests fail. That'd just make things a bit more clean.

Better labling for errors

Some labels like too big can be a bit more descriptive.

Make use of humanize.Number in Reddit score in LSF tooltips

Curerntly we do not do that, example https://livestreamfails.com/clip/116152:

Tweet Link Thumbnails: Compose Multiple Images into Collage

Tweets can have multiple images attached (see e.g. this one). It would be nice to compose all images into a collage for the generated thumbnail. In our current architecture, this would require some server-side processing. One tool that can do this is imagemagick via the montage subcommand but there might be something else better suited for our purposes.

Re-add youtube dislikes

What service do you want support added for?

Return YouTube Dislikes

Links

https://returnyoutubedislikeapi.com/swagger/index.html

Thumbnail

YouTube dislikes next to the likes - where they were before (that were removed because youtube is a bunch of poopy doodoo heads)

Additional information

We'd look at using a 24h cache period, as they mention on their website, the "dislikes are cached and they aren't updated very frequently. It varies on video popularity but can take anywhere between a few hours and a few days days to update."

Link titles not escaped

Take for example:

https://clips.twitch.tv/NurturingShakingPrariedogKeyboardCat

In chatterino the <3 is not displayed because it's not escaped properly.

The html specials should be escaped here:

https://github.com/pajlada/chatterino-api-cache/blob/36c767d4650a2ef3cbfaf4fa2fdb9950be7cf505/link_resolver_twitchclips.go#L27

Add thumbnails for betterttv emote links

I would like for links like https://betterttv.com/emotes/<hexadecimal emote id> to have thumbnails to see the emotes, the emote image address is https://cdn.betterttv.net/emote/<hexadecimal emote id>/3x

Example

bttv emote link: https://betterttv.com/emotes/5c07ca765f63c823e97fe4d2
image link: https://cdn.betterttv.net/emote/5c07ca765f63c823e97fe4d2/3x

Add m.twitch.tv/clip/ support

What service do you want support added for?

Additional support for twitch clips. While fairly rare, the domain is valid for twitch clips.

Links

1. https://m.twitch.tv/clip/LachrymoseSwissLatteDancingBanana-ZsNQ8Ew9vI9Nvrk0
2. https://m.twitch.tv/clip/ScaryAmorphousStorkFreakinStinkin-yH1MLafG_msGhUIt

Additional information

I only didn't do it myself in case some logic needs to be changed and not just a minor regex change.

Add support for imgur.com subdomain imgur.io

What service do you want support added for?

Apparently this is a subdomain of imgur.com - never heard of it until today but it seems valid.
(honestly it looks like a future garbage layout they might implement on imgur.com)
I assume the current implementation will load the first image on this domain, similar to how the link resolver works with galleries.

Links

1. https://imgur.io/5DaePph vs https://imgur.com/5DaePph
2. https://imgur.io/xq9awUX vs https://imgur.com/xq9awUX

Expected Thumbnail

Additional information

The imgur.io direct links use this ugly struct https://i.imgur.com/xq9awUX_d.webp?maxwidth=640&shape=thumb&fidelity=medium but since they are imgur.com links we already handle them.

maybe we could use a list incase imgur adds any future domains ~~ 👻

Remove /twitchemotes/set/:setID endpoint

Chatterino no longer makes use of the /twitchemotes/set/:setID endpoint provided by this API. Could this be removed?

@pajlada you might have metrics on external callers. I doubt anyone else is using it but would suck to drop it with 0 notice

Twitter link preview - broadcasts

Recently a preview for twitter links was added. Twitter broadcast links show no preview.
Should be added?

Suggestion to add new endpoint: /contributors

New endpoint would serve content of
https://raw.githubusercontent.com/Chatterino/chatterino2/master/resources/contributors.txt
in json format, looking like this:

{
    "username": "YungLPR",
    "link": "https://github.com/leon-richardt"
    "avatar": null,
    "title": "Contributor",
},
{
    "username": "Mm2PL",
    "link": "https://github.com/mm2pl"
    "avatar": "https://raw.githubusercontent.com/Chatterino/chatterino2/master/resources/avatars/mm2pl.png",
    "title": "Contributor",
}

cached for 12h, reparsed only when contributors.txt SHA changes

Why

This way chatterino wont need to bundle constantly growing list of avatars, it will dynamically request avatars when user visits About page.

Other pros:

• longterm solution which will work as good with 100+ avatars in future
• no changes in current process of adding new contributors, everything stays in place
• no rebuild needed for updates, previous chatterino versions will also get up-to-date list
• current binary files will be ~400kb smaller (6%)
• probably minor build time improvement
• possibility to include other dynamic data, like current count of commits

If it gets approved im happy to PR it on both repos

Make the Twitter link resolver resolve nitter links as well

They're literally the same link format except for the domain name. (Probably a good first issue 😉 )

Wikipedia title should use titles.Normalized instead of titles.Display

When querying the Wikipedia page summary API for an article we get 3 different title keys:
canonical, normalized, and display.
we currently use display, which seems fine for most cases but for pages like https://en.wikipedia.org/wiki/Test_(2013_film) with Display we get the italized version which shows up as Test in the tooltip right now.

We should probably move to the "normalized" key instead

Add docs for obtaining all api keys required

Migrate Twitch clips resolver to Helix API

Twitch has recently added duration field to Helix's Get Clips endpoint. We could migrate from gotwitch to helix library, which already has added support for duration field in Get Clips method.

I'll go ahead, update branch on my fork (which I've been already maintaining for quite a while) unless someone finds a better Helix library.

Make the link resolver respect robots.txt

This might help in the implementation: https://github.com/t94j0/robots
I don't want the link resolver to make expensive queries on my website when someone posts a link in chat :)

Add gif support in thumbnails

Facebook oEmbed Changes

Refer this article: https://developers.facebook.com/docs/plugins/oembed/

The oEmbed product has been replaced with the oEmbed Read feature. If you implemented the oEmbed product before June 8, 2021, you have until September 7, 2021 to complete App Review for the oEmbed Read feature. If you have not been approved for the oEmbed Read feature by September 7, 2021, your oEmbed implementations will fail to load.

I don't really help with the api that often and am unsure if this actually affects us, but I thought I'd bring it to attention anyway.

Twitchemotes API died resulting in all /twitchemotes/set/ calls return 404

See Chatterino/chatterino2#2904
Needs #170

Replace twitchemotes' API with Helix equivalents

In nicklaw5/helix 1.20.0 there were added methods supporting getting information about emote sets. It's worth checking if we can use that in order to replace third-party twirchemotes' API. Is it worth doing so though?

Add maxThumbnailSize to config

I have a self-hosted Chatterino-API and I'd like to change some of the const/vars that are all over the place but change them in the new config.yaml file instead.

Specifically, my request today is the maxThumbnailSize over here:
https://github.com/Chatterino/api/blob/master/pkg/thumbnail/thumbnail.go#L33

Thank you.

Image thumbnails are rotated sometimes

In some cases (Can't figure out which yet) image thumbnails are rotated.

Example Picture:
https://files.catbox.moe/8c5ref.jpeg

Serve Link Info for PDFs

What service do you want support added for?

Similar to image files, serve thumbnails for PDFs. I'm not sure what a perfect behavior would be yet, this can be discussed in this issue.

A naive implementation might just take the first page of the thumbnail and render it to a PNG. More advanced implementations might attempt to parse text and provide that as the thumbnail text or arrange multiple PDF pages into a nice preview.

Links

1. https://github.com/leon-richardt/green-networking/raw/194cfcc20bb059c62f5b305b1a58f17c28d8c1c4/Presentation/server_consolidation.pdf
2. https://www.cs.virginia.edu/~robins/Turing_Paper_1936.pdf

Explore if we can serve image thumbnail for WebP images with reasonable effort

Example URL for which I would like a thumbnail served: https://artflowbucket-new.s3.amazonaws.com/generated/92fc3c00e617436e930cd9307974a72f.webp

This might need client-side support from Chatterino2 unless we want to convert the images before sending them

Support for YouTube live streams

Research if we can detect if a YouTube link is a Live Stream, potentially with information about when it goes live, when it went live etc. Given the more volatile nature of live streams, we might want to return a lower cache value for these

Normalize shared constants

Some values we use are the same among many services (e.g. timestamp formats) yet are reimplemented every time

we should have some sort of god of war package that can hold this

Check if we can get a higher quality thumbnail from Twitter

Current thumbnail is ugly

https://i.nuuls.com/grHZE.png

see if we can find a nicer one

Link info on youtube.com/embed does not work

Cross-post from Chatterino/chatterino2#784

Merge 2 resolver.CustomURLManager objects into 1 in twitch's custom resolver

Currently we declare two separate custom resolvers for twitch clips Which is inefficient.
This can be easily avoided by applying simiar approach with regular expression like in Discord resolver or a domain map in BetterTTV one.
I could try fixing this on my own to learn something new

Code I'm talking about:

api/internal/resolvers/twitch/resolver.go

Lines 74 to 106 in 5bc8059

	// Find clips that look like https://clips.twitch.tv/SlugHere
	resolvers = append(resolvers, resolver.CustomURLManager{
	Check: func(url *url.URL) bool {
	return utils.IsDomain(url, "clips.twitch.tv")
	},
	Run: func(url *url.URL, r *http.Request) ([]byte, error) {
	pathParts := strings.Split(strings.TrimPrefix(url.Path, "/"), "/")
	clipSlug := pathParts[0]
	apiResponse := clipCache.Get(clipSlug, r)
	return json.Marshal(apiResponse)
	},
	})
	// Find clips that look like https://twitch.tv/StreamerName/clip/SlugHere
	resolvers = append(resolvers, resolver.CustomURLManager{
	Check: func(url *url.URL) bool {
	if !strings.HasSuffix(url.Host, "twitch.tv") {
	return false
	}
	pathParts := strings.Split(url.Path, "/")
	return len(pathParts) >= 4 && pathParts[2] == "clip"
	},
	Run: func(url *url.URL, r *http.Request) ([]byte, error) {
	pathParts := strings.Split(strings.TrimPrefix(url.Path, "/"), "/")
	clipSlug := pathParts[2]
	apiResponse := clipCache.Get(clipSlug, r)
	return json.Marshal(apiResponse)
	},
	})

Move main package into cmd/api

The main package (so all .go files) in the root folder should be moved into the cmd/api folder instead

cfg should not be a singleton in main package

Right now, cfg is a singleton defined in cmd/api/main.go. This should instead be loaded inside the main() function and passed through to where needed

Certain twitter links should be blacklisted from user searching

The chatterino api appears to use a "anything after the / is classified as a user" approach, but this is not the case for urls like https://twitter.com/settings

We should have a blacklist where the api does not search for that user through the twitter module, but just parses it through the normal link fetcher.

Other links affected (possibly more):
https://twitter.com/home
https://twitter.com/explore
https://twitter.com/notifications
https://twitter.com/messages
https://twitter.com/i/bookmarks
https://twitter.com/user/lists
https://twitter.com/user/topics
https://twitter.com/user/moments
https://twitter.com/i/newsletters
https://twitter.com/settings
https://twitter.com/i/display
https://twitter.com/i/keyboard_shortcuts

Youtube Shorts support

What service do you want support added for?

Preview/information for Youtube shorts, just like for "normal" Youtube videos, when posted using the "shorts" link format.

Links

https://www.youtube.com/shorts/Q9QdFTuuPOI
https://www.youtube.com/shorts/IefWjRpK4f0

Thumbnail

Same data as with "normal" youtube videos.

Additional information

When renaming the links to the standard watch?v= format the preview works normally.

Thank you!

Use content-type: application/json for responses

I noticed that api often (if not always, haven't tested everything) has a header content-type: text/plain and afaik api returns only json data, so maybe that can be changed (?)

Pass http.Request to load functions in custom resolvers

This would be necessary for proxying thumbnails in custom resolvers, because utils.FormatThumbnailURL takes *http.Request as an argument, however it is a nil in that scope, making it impossible to call that method.

Add a channel when hovering over sub emotes

In regular twitch chat, when you click on an emote, it will show the channel that it's from