mirror of https://github.com/Sonarr/Sonarr
Fixed headings syntax
⮚ Ondrej Fabry ⮘
parent
a866862734
commit
61521ded22
|
|
@ -1,22 +1,22 @@
|
|||
##Introduction##
|
||||
## Introduction
|
||||
|
||||
Sonarr supports a Newznab-like api dubbed **Torznab**. This api offers a standardized recent/search api for both tv and movies (of which Sonarr only uses tv).
|
||||
The Newznab api specification is built around a simple rss feed with filtering and paging capabilities. It was designed for usenet primarily, but it can be easily adapted for torrents.
|
||||
|
||||
The purpose of this wiki page is to describe the differences with Newznab and some recommendations to implement a custom proxy/indexer.
|
||||
|
||||
###Private Trackers###
|
||||
### Private Trackers
|
||||
|
||||
Many torrent trackers thrive on the community and may have rules in place that mandate site visits, karma, votes, comments and all. Having an API doesn't need to be detrimental to this goal.
|
||||
A site can integrate the api into the existing karma/bonus system to keep users engaged in the community. There are quite a few creative ways of doing this.
|
||||
|
||||
**Note:** If your torrent tracker is based on a generic tracker software, please coordinate to get the api implemented in the generic base code so everyone can benefit and to avoid double work.
|
||||
|
||||
##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.
|
||||
|
||||
###Newznab/Torznab queries###
|
||||
### Newznab/Torznab queries
|
||||
|
||||
Originally Newznab defined 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.
|
||||
In later versions, Newznab returns a list of the supported query params in the `t=caps` response via a `supportedParams` attribute.
|
||||
|
|
@ -53,13 +53,13 @@ Examples:
|
|||
`/api?t=tvsearch&cat=..,..&rid=143&tvdbid=1232&season=1&ep=2` should perform a database query like `SELECT * FROM Releases WHERE (rid=143 OR tvdbid=1232) AND season=1 AND ep=2`.
|
||||
So `q AND (rid OR tvdbid OR tvmazeid) AND season AND ep`.
|
||||
|
||||
###Caps endpoint###
|
||||
### 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. However, newznab specifies a list of default categories.
|
||||
It's recommended to keep those categories intact, Client applications can then query one of the defaults, instea
|
||||
It's recommended to keep those categories intact, Client applications can then query one of the defaults, instead.
|
||||
|
||||
Many torrent sites have their own rss 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.
|
||||
|
|
@ -111,7 +111,7 @@ Example `t=caps` response:
|
|||
```
|
||||
|
||||
|
||||
###Torznab results###
|
||||
### Torznab results
|
||||
First and foremost: Torznab indexers should return `application/x-bittorrent` as enclosure type:
|
||||
```
|
||||
<enclosure url="https://yoursite.com/download.php?torrent=123&passkey=123456"
|
||||
|
|
@ -146,7 +146,7 @@ All these attributes are optional, the bold ones are recommended. Please note th
|
|||
| **downloadvolumefactor** | double | factor for the download volume, in most cases it should be set to 1, if a torrent is set to freeleech set it to 0, if only 50% is counted set it to 0.5 |
|
||||
| **uploadvolumefactor** | double | factor for the upload volume, in most cases it should be set to 1, if a torrent is set to neutral leech (upload is not counted) set it to 0, if it's set to double upload set it to 2 |
|
||||
|
||||
###Minimum ratio/seedtime###
|
||||
### Minimum ratio/seedtime
|
||||
|
||||
These two attributes are included to allow a torrent tracker to specify the seeding requirements on a per torrent basis.
|
||||
These values should be set to the long term requirements for the torrent. So if it's freeleech for a decade, you can set minimumratio to 0.0, but if it's only for a day, keep it at 1.0. (0.0 is a bit drastic, but you get the point)
|
||||
|
|
@ -155,7 +155,7 @@ 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 and/or warn the user to avoid HnRs.
|
||||
|
||||
|
||||
##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```.
|
||||
- Double check enclosure url, size and type.
|
||||
|
|
@ -167,7 +167,7 @@ Specifying one or both of these attributes is recommended, because it allows fut
|
|||
- Implement the ```t=caps``` endpoint, feel free to put it behind an apikey check.
|
||||
- Please only use the apikey for authentication, don't mandate cookies or other authentication.
|
||||
|
||||
##Some References##
|
||||
## Some References
|
||||
Newznab specification: http://newznab.readthedocs.org/en/latest/misc/api/
|
||||
nZEDb specification: https://github.com/nZEDb/nZEDb/blob/0.x/docs/newznab_api_specification.txt
|
||||
Torznab xml attributes: https://github.com/Sonarr/Sonarr/blob/develop/schemas/torznab.xsd
|
||||
|
|
|
|||
Loading…
Reference in New Issue