2024-05-18T05:25:52Z

Ajay: add kotlin lib

The DeArrow API is free to use for all non browser-extensions
-----{{API Docs}}

'''Libraries''': [https://github.com/zt64/dearrow-kt Kotlin]
-----

===== '''GET''' <code>/api/branding</code> =====
Get submission for a video.

Note: Data is returned in order of quality. You can use the first element. However, you should make sure the first element has either locked = true or votes >= 0. If not, it is considered untrusted and is only to be shown in the voting box until it has been confirmed by another user.

Random time and video duration are used if you want to fallback thumbnails to a screenshot from a random time. To make thumbnail caching possible, this random time is consistent and produced by the server. The random time value is a number between 0 and 1 and must be multiplied by the video duration. For convenience, the API returns the video duration if it is known, but for most videos the server does not know the video duration. When the API returns a video duration of 0 or null, you must either not use this feature, or obtain the video duration using another method. The browser extension will fallback to fetching the video duration using other methods to always be able to use the feature.

'''Input''' (URL Parameters):<syntaxhighlight lang="ts">
{
videoID: string,
service: string, // Optional, default is 'YouTube' [1]
returnUserID: boolean, // optional, returns submitter userIDs if true, default false
fetchAll: boolean // optional, hides details with negative score if false, default false
}
</syntaxhighlight>References: <ref name=":1">Service to get segments for. See [[Types#Service|Types]] for supported services</ref>

'''Response''':<syntaxhighlight lang="ts">
{
titles: Array<{
title: string, // Note: Titles will sometimes contain > before a word. This tells the auto-formatter to not format a word. If you have no auto-formatter, you can ignore this and replace it with an empty string
original: boolean,
votes: number,
locked: boolean,
UUID: string,
userID: string // only present if requested
}>:
thumbnails: Array<{
timestamp: number, // null if original is true
original: boolean,
votes: number,
locked: boolean,
UUID: string,
userID: string // only present if requested
}>
randomTime: number,
videoDuration: number | null
}
</syntaxhighlight>'''Error codes''':

400: Bad Request (Your inputs are wrong/impossible)

404: Not Found
-----
====='''GET''' <code>/api/branding/:sha256HashPrefix</code>=====
Get submissions for a video.

<code>sha256HashPrefix</code> is a hash of the YouTube <code>videoID</code>. It should be the first 4 characters. This provides extra privacy by potentially finding more than just the video you are looking for since the server will not know exactly what video you are looking for.

Note: Data is returned ordered. You can use the first element. However, you should make sure the first element has either locked = true or votes >= 0. If not, it is considered untrusted and is only to be shown in the voting box until it has been confirmed by another user.

Random time and video duration are used if you want to fallback thumbnails to a screenshot from a random time. To make thumbnail caching possible, this random time is consistent and produced by the server. The random time value is a number between 0 and 1 and must be multiplied by the video duration. For convenience, the API returns the video duration if it is known, but for most videos the server does not know the video duration. When the API returns a video duration of 0 or null, you must either not use this feature, or obtain the video duration using another method. The browser extension will fallback to fetching the video duration using other methods to always be able to use the feature.

'''Input''' (URL Parameters):<syntaxhighlight lang="ts">
{
service: string // Optional, default is 'YouTube'. [1]
returnUserID: boolean, // optional, returns submitter userIDs if true, default false
fetchAll: boolean // optional, hides details with negative score if false, default false
}
</syntaxhighlight>References: <ref name=":1" />

'''Response'''<syntaxhighlight lang="ts">
{
[videoID: string]: {
titles: Array<{
title: string,
original: boolean,
votes: number,
locked: boolean,
UUID: string,
userID: string // only present if requested
}>:
thumbnails: Array<{
timestamp: number, // null if original is true
original: boolean,
votes: number,
locked: boolean,
UUID: string,
userID: string // only present if requested
}>,
randomTime: number,
videoDuration: number | null
}
}
</syntaxhighlight>'''Error codes''':

400: Bad Request (Your inputs are wrong/impossible)

404: Not Found
-----
====='''POST''' <code>/api/branding</code>=====
Create a submission on a video. If a duplicate submission exists, it votes on that submission.

'''Input''' (JSON Body):<syntaxhighlight lang="ts">
{
videoID: string,
userID: string, // This should be a randomly generated UUID stored locally (not the public one)
userAgent: string, // "Name of Client/Version" or "[BOT] Name of Bot/Version" ex. "Chromium/1.0.0"
service: string, // Optional, default is 'YouTube'. [1]
title: { // Optional, you can submit either just a title, or just a thumbnail, or both
title: string,
},
thumbnail: {
timestamp: number, // Optional if original is true
original: boolean
},
downvote: boolean, // Optional, setting to true downvotes instead of upvoting, will error if the submissions don't exist
autoLock: boolean, // Optional, applies to VIPs only, default true, set to false to vote as a regular user
}
</syntaxhighlight>References: <ref name=":1" />

'''Error codes''':

400: Bad Request (Your inputs are wrong/impossible)

500: Internal Server Error (you tried to downvote a submission that doesn't exist)
-----

=== Generating a thumbnail from a timestamp ===
Generating thumbnails is handled by a different service. This service will generate thumbnails, and cache them for future users. It is not guaranteed to return, and uses a queuing system. The browser extension uses a fallback local rendering system to handle this, and will render it locally when the server is not able to. It does this by taking a screenshot a video element.

This service is state-less, so can easily be [https://github.com/ajayyy/DeArrowThumbnailCache self-hosted] without having to sync submissions from the main server.

The main instance is hosted at <code><nowiki>https://dearrow-thumb.ajay.app</nowiki></code>

The basic endpoint is as follows

===== '''GET''' <code>/api/v1/getThumbnail</code> =====
Get submissions for a video.

'''Input''' (URL Parameters):<syntaxhighlight lang="ts">
{
videoID: string,
time: number
}
</syntaxhighlight>References: <ref name=":1" />

'''Response''':

A binary image response.

'''Response codes''' (PLEASE READ):

200: Ok

204: No content, failed to generate, or chose not to generate (reason in <code>X-Failure-Reason</code> header)

==== Speeding up requests ====
You can speed up requests by making a request to <code>getThumbnail</code> at the same time as a request to branding, but without providing a value in the <code>time</code> field. The server will respond with an image if it has one. Once both requests are done, you then have to make sure the thumbnail is for the correct timestamps.

You need to check the <code>X-Timestamp</code> header and verify it is the same as the branding response. If it is not, then you must make a second request with the new time.

There also is a <code>X-Title</code> header that is used by the extension as a fallback in the result that the main server goes down.

<references />
[[Category:Developer Reference]]
[[Category:DeArrow]]