mirror of
https://github.com/Sonarr/Sonarr
synced 2025-01-03 05:35:29 +00:00
Updated request, caps and response details and examples. Included supportedParams.
Taloth
parent
09a510aabd
commit
fb0f214ca7
1 changed files with 93 additions and 15 deletions
|
|
@ -11,6 +11,99 @@ It's also imperative to think about how to integrate this in your existing karma
|
||||||
|
|
||||||
##Differences with Newznab##
|
##Differences with Newznab##
|
||||||
|
|
||||||
|
Torznab extends on Newznab on a couple of points to make it more useful. However, it is in principle backward compatible.
|
||||||
|
|
||||||
|
###Torznab queries###
|
||||||
|
|
||||||
|
Newznab defines the query params `q,rid,season,ep` for `t=tvsearch` and `q` for `t=search`, however not all sites support tvrage ids, and therefore would have to be queries with the q= param.
|
||||||
|
Torznab implementations should return the supported query params in their `t=caps` response. (more on `caps` later)
|
||||||
|
Implementations should also take care in returning appropriate responses when a query includes an unsupported newznab parameter, for example, if rid is not supported, return an empty result set.
|
||||||
|
This is to remain backward compatibility with clients that do not query the caps.
|
||||||
|
|
||||||
|
Newznab does not define `tvdbid=` and `imdbid=`, but implementors are recommended to support these if possible.
|
||||||
|
|
||||||
|
```
|
||||||
|
t=tvsearch:
|
||||||
|
Newznab query params: q,rid,season,ep
|
||||||
|
Torznab query params: tvdbid
|
||||||
|
t=search:
|
||||||
|
Newznab query params: q
|
||||||
|
t=movie:
|
||||||
|
Newznab query params: q
|
||||||
|
Torznab query params: imdbid
|
||||||
|
```
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
```
|
||||||
|
?t=tvsearch&cat=..,..&rid=..&season=1&episode=1
|
||||||
|
?t=tvsearch&cat=..,..&q=..&season=1&episode=1
|
||||||
|
|
||||||
|
?t=tvsearch&cat=..,..&rid=..&season=2016&ep=12/20
|
||||||
|
?t=tvsearch&cat=..,..&q=..&season=2016&ep=12/20
|
||||||
|
|
||||||
|
?t=search&cat=..,..&q=Anime+Title+123
|
||||||
|
?t=search&cat=..,..&q=Fantastic+Series+With+Episode+Title+For+Special
|
||||||
|
```
|
||||||
|
|
||||||
|
###Torznab caps endpoint###
|
||||||
|
|
||||||
|
The mode `t=caps` is supposed to return the capabilities and categories of the newznab/torznab indexer.
|
||||||
|
Implementing this mode is mandatory.
|
||||||
|
|
||||||
|
The caps response for torznab is mostly the same as newznab, except for a few points:
|
||||||
|
|
||||||
|
The `searching` element is normally used to specify what kind of modes (`tvsearch`,`search`,`movie`) the api supports. But torznab adds an optional `supportedParams` attribute allowing the api to specify which query params are supported.
|
||||||
|
If the `supportedParams` attribute is not found, then it defaults to the original newznab params as specified earlier.
|
||||||
|
|
||||||
|
Many torrent sites have their own categories starting at '1', it's recommended NOT to map these 1 to 1 on newznab categories but instead add 100000 to the number.
|
||||||
|
That way it falls in the site specific range and does not interfere with the original newznab categories.
|
||||||
|
The api should then alias all site-specific categories in one of the original newznab category.
|
||||||
|
For example, if you have category 10 as Blu-Ray 1080p TV, then releases in that category would use the torznab api cats 100010,5040,5000 (Site-specific, TV/HD, TV).
|
||||||
|
Any query that includes any of those numbers in the `cat=` parameter would return those releases as results.
|
||||||
|
Of course it's also allowed to omit the site-specific categories entirely, and map only on newznab categories.
|
||||||
|
|
||||||
|
Example `t=caps` response:
|
||||||
|
```
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<caps>
|
||||||
|
<!-- server information -->
|
||||||
|
<server version="1.0" title="site" strapline="..."
|
||||||
|
email="info@site.com" url="http://servername.com/" image="http://servername.com/theme/black/images/banner.jpg"/>
|
||||||
|
|
||||||
|
<limits max="100" default="50"/>
|
||||||
|
|
||||||
|
<registration available="yes" open="yes" />
|
||||||
|
|
||||||
|
<searching>
|
||||||
|
<search available="yes" supportedParams="q" />
|
||||||
|
<tv-search available="yes" supportedParams="q,rid,season,ep" />
|
||||||
|
<movie-search available="no" supportedParams="q" />
|
||||||
|
</searching>
|
||||||
|
|
||||||
|
<!-- supported categories -->
|
||||||
|
<categories>
|
||||||
|
<category id="1000" name="Console">
|
||||||
|
<subcat id="1010" name="NDS"/>
|
||||||
|
<subcat id="1020" name="PSP"/>
|
||||||
|
</category>
|
||||||
|
<category id="2000" name="Movies">
|
||||||
|
<subcat id="2010" name="Foreign"/>
|
||||||
|
</category>
|
||||||
|
|
||||||
|
<!-- site specific categories -->
|
||||||
|
<category id="100001" name="MotoGP" description="Latest MotoGP stuff"/>
|
||||||
|
<category id="100002" name="Fifa 2010" description="Fifa 2010 world cup">
|
||||||
|
<subcat id="100003" name="Fifa 2010 HD" description="HD stuff"/>
|
||||||
|
<subcat id="100004" name="Fifa 2010 SD" description="SD stuff"/>
|
||||||
|
</category>
|
||||||
|
<!-- etc.. -->
|
||||||
|
</categories>
|
||||||
|
</caps>
|
||||||
|
</xml>
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
###Torznab results###
|
||||||
First and foremost: Torznab indexers should return application/x-bittorrent as enclosure type:
|
First and foremost: Torznab indexers should return application/x-bittorrent as enclosure type:
|
||||||
```
|
```
|
||||||
<enclosure url="https://yoursite.com/download.php?torrent=123&passkey=123456"
|
<enclosure url="https://yoursite.com/download.php?torrent=123&passkey=123456"
|
||||||
|
|
@ -47,21 +140,6 @@ The idea is that if one of the two criteria is satisfied, the torrent client can
|
||||||
|
|
||||||
Specifying one or both of these attributes is recommended, because it allows future clients to appropriately adjust the seeding configuration of the torrent client.
|
Specifying one or both of these attributes is recommended, because it allows future clients to appropriately adjust the seeding configuration of the torrent client.
|
||||||
|
|
||||||
##Recommended query params##
|
|
||||||
|
|
||||||
Incomplete list of what should be supported.
|
|
||||||
|
|
||||||
```
|
|
||||||
?t=tvsearch&cat=..,..&rid=..&season=1&episode=1
|
|
||||||
?t=tvsearch&cat=..,..&q=..&season=1&episode=1
|
|
||||||
|
|
||||||
?t=tvsearch&cat=..,..&rid=..&season=2016&episode=12/20
|
|
||||||
?t=tvsearch&cat=..,..&q=..&season=2016&episode=12/20
|
|
||||||
|
|
||||||
?t=search&cat=..,..&q=Anime+Title+123
|
|
||||||
?t=search&cat=..,..&q=Fantastic+Series+With+Episode+Title+For+Special
|
|
||||||
```
|
|
||||||
|
|
||||||
##Hints and gotta's##
|
##Hints and gotta's##
|
||||||
|
|
||||||
- Make sure your api properly handles the ```Accept``` and ```Content-Type``` http headers. Rss should have one of these mime-types ```application/rss+xml, text/rss+xml, text/xml```. Whatever you do, do _not_ use ```text/html```.
|
- Make sure your api properly handles the ```Accept``` and ```Content-Type``` http headers. Rss should have one of these mime-types ```application/rss+xml, text/rss+xml, text/xml```. Whatever you do, do _not_ use ```text/html```.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue