546
edits
UDP API Definition: Difference between revisions
m
→Basics
Epoximator (talk | contribs) |
Epoximator (talk | contribs) m (→Basics) |
||
| Line 29: | Line 29: | ||
=== General === | === General === | ||
{three digit return code} {str return string}\n | {three digit return code} {str return string}\n | ||
{data field 0}|{data field 1}|...|{data field n}\n | {data field 0}|{data field 1}|...|{data field n}\n | ||
The network communication is ''packet'' and ''line'' based. Each ANIDB API command is exactly one UDP packet containing one line. Results are sent as one packet but may consist out of multiple lines. A return value always starts with a 3 byte result code followed by a human redable version of the result code. Be aware that important data fields may be returned directly after the return code (see: 200,201,271,272,504). | |||
The meaning for all result codes can be found in this document. If there is more than one entry returned, it's one entry per line. Lines are terminated by a <tt>\n</tt> (no dos linefeed <tt>\r</tt>). The elements of a format string are seperated by a "|" character. | |||
A | |||
'''IMPORTANT:''' | |||
A client should ignore any additional trailing data fields it doesn't expect. Additional fields are going to be added to the output of some commands from time to time. Those additional fields will simply be appended to the end of the existing output. | * All commands except PING '''requires''' login, meaning that the ''session tag'' must be set (<tt>s=xxxxx</tt>). | ||
A client should be written in a way so that it is not affected by such new fields. | * A client should ignore any additional trailing data fields it doesn't expect. Additional fields are going to be added to the output of some commands from time to time. Those additional fields will simply be appended to the end of the existing output. A client should be written in a way so that it is not affected by such new fields. | ||
* Due to the length constraints of an UDP package the replies from the server will never exceed 1400 bytes. String fields will be truncated if necessary to ensure this. No warnings are given when this happens. | |||
* A client should handle all possible return codes for each command. | |||
Due to the length | ** Possible return codes for '''all commands''': | ||
*** 505 ILLEGAL INPUT OR ACCESS DENIED | |||
*** 555 BANNED | |||
*** 598 UNKNOWN COMMAND | |||
*** 600 INTERNAL SERVER ERROR | |||
*** 601 ANIDB OUT OF SERVICE - TRY AGAIN LATER | |||
** Additional return codes for all commands that '''require login''': | |||
*** 501 LOGIN FIRST | |||
*** 502 ACCESS DENIED | |||
*** 506 INVALID SESSION | |||
{{eyecatch|NOTE:| The '555 BANNED' message should not be expected by the client. This message is only enabled temporary to help developers understand what they are doing wrong.}} | |||
{{eyecatch|NOTE:| | |||
{{eyecatch| | |||
While in daily maintenance the AniDB API will reply with | While in daily maintenance the AniDB API will reply with | ||
601 ANIDB OUT OF SERVICE - TRY AGAIN LATER | 601 ANIDB OUT OF SERVICE - TRY AGAIN LATER | ||
to all commands. | to all commands. If a client recieves such a return value it should wait at least 30 minutes before trying again. | ||
}} | }} | ||
=== Server / UDP Connection: === | |||
{{eyecatch|NOTE:| | The Client has to send data packets to: | ||
* '''Server:''' api.anidb.info | |||
* '''Port:''' 9000/UDP | |||
The servername and port should not be hardcoded into a frontend but should be read from a configuration file. | |||
=== Server Errors === | |||
* At any time the API might return a fatal error of the form: | |||
: <tt>6xx ERROR DESCRIPTION</tt> | |||
* Possible codes are 600-699. | |||
* Occurances of these errors (except 601) should be reported to [[User:Epoximator|epoximator]]. | |||
{{eyecatch|NOTE:| 6XX messages do not always return the tags given with the command which caused the error!}} | |||
=== Connection Problems === | === Connection Problems === | ||
There are many ways for a client to end up banned or the API might currently be handling too many concurrent connections. | There are many ways for a client to end up banned or the API might currently be handling too many concurrent connections. | ||
If a client does not get any reply to an AUTH command it should start to increase the retry delay exponentially with every failed login attempt. (i.e. try again after 30 seconds if the first login attempt failed, if the second fails too retry after 2 minutes, then 5 minutes, then 10 minutes, then 30 minutes, ... until you reach a retry delay of ~2-4h.) | If a client does not get any reply to an AUTH command it should start to increase the retry delay exponentially with every failed login attempt. (i.e. try again after 30 seconds if the first login attempt failed, if the second fails too retry after 2 minutes, then 5 minutes, then 10 minutes, then 30 minutes, ... until you reach a retry delay of ~2-4h.) | ||
=== Local Port === | === Local Port === | ||
A client should select a fixed local port >1024 at install time and reuse it for local UDP Sockets. If the API sees too many different UDP Ports from one IP within ~1 hour it will ban the IP. (So make sure you're reusing your UDP ports also for testing/debuging!) | A client should select a fixed local port >1024 at install time and reuse it for local UDP Sockets. If the API sees too many different UDP Ports from one IP within ~1 hour it will ban the IP. (So make sure you're reusing your UDP ports also for testing/debuging!) | ||
The local port may be hardcoded, however, an option to manually specify another port should be offered | The local port may be hardcoded, however, an option to manually specify another port should be offered. | ||
Note when behind a [http://en.wikipedia.org/wiki/Network_address_translation NAT]/masquerading router: | '''Note when behind a [http://en.wikipedia.org/wiki/Network_address_translation NAT]/masquerading router:'''<br/> | ||
A session between the server and a client is identified by the ip and port used by the client. So when the port (or ip) changes within a session the client has to authenticate again. If a client is behind a nat router it can’t actually control the local port used for the connection. The router will normally translate the port to support several computers on a lan to share the internet connection. The public port (as determined by the router and seen by the server) which has been assigned to the connection will only be reserved for as long as it is in use. This means that the router will usually deallocate the port after a fixed timeout period (i.e. 5, 10 or 15 minutes). Once that happens the client will no longer be able to receive UDP messages from the server (the messages will be discarded as undeliverable by the router) and a new port will be selected once the client tries to send a message to the server (which will result in a new connection session - NOTE: this could get you banned!, see above). | A session between the server and a client is identified by the ''ip and port'' used by the client. So when the port (or ip) changes within a session the client has to authenticate again. If a client is behind a nat router it can’t actually control the local port used for the connection. The router will normally ''translate'' the port to support several computers on a lan to share the internet connection. The public port (as determined by the router and seen by the server) which has been assigned to the connection will only be reserved for as long as it is in use. This means that the router will usually ''deallocate the port after a fixed timeout period'' (i.e. 5, 10 or 15 minutes). Once that happens the client will no longer be able to receive UDP messages from the server (the messages will be discarded as undeliverable by the router) and a new port will be selected once the client tries to send a message to the server (which will result in a new connection session - NOTE: this could get you banned!, see above). So in order to keep a session over a NAT router alive, the client has to ping the server within this period to prevent a timeout. | ||
So in order to keep a session over a NAT router alive, the client has to ping the server within this period to prevent a timeout. | |||
The client can decide whether it is behind a NAT router or not by adding | The client can decide whether it is behind a NAT router or not by adding <tt>nat=1</tt> to the AUTH command. This will cause the response to include the ip and port as seen by the server. If the port differs from the port reported by the local socket, the connection subject to NAT and the client should issue PING commands in regular intervals. Please do not send pings more often then once every 5 minutes and only on connections via NAT routers or if the user has explicitly enabled regular keepalive pings via a configuration setting (default setting should be OFF). | ||
Please do not send pings more often then once every 5 minutes and only on connections via NAT routers or if the user has explicitly enabled regular keepalive pings via a configuration setting (default setting should be OFF). | |||
=== Flood Protection === | === Flood Protection === | ||
To prevent high server load the UDP API server enforces a strict flood protection policy. | To prevent high server load the UDP API server enforces a strict flood protection policy. | ||
* Short Term: | |||
** A Client MUST NOT send more than 0.5 packets per second. | |||
** The server will start to enforce the limit after the first 5 packets have been recieved. | |||
* Long Term: | |||
** A Client MUST NOT send more than one packet every 30 seconds over an extended amount of time. | |||
** ''An extended amount of time'' is not defined. Use common sense. | |||
Once a client exceeds a rate limit all further UDP packets from that client will be dropped without feedback until the client's packet rate is back down to acceptable levels. | Once a client exceeds a rate limit all further UDP packets from that client will be dropped without feedback until the client's packet rate is back down to acceptable levels. | ||
| Line 124: | Line 110: | ||
}} | }} | ||
=== Anti Leech Protection === | |||
The API should not be used to "download" AniDB. If such attempts are detected you will get banned. | |||
=== Caching === | |||
To minimize server and network load a client should use local caching in order to prevent repeated API requests for the same data. | |||
A client should locally cache FILE/EP/ANIME/GROUP/... info wherever possible for extended amounts of time. | |||
(I.e. if a client is used to scan a local folder with anime files and add them via API to a users mylist then it shall only ask for all files in the first run and cache the info for all files known to AniDB. If run again over the same folder it shall only check those files which were unknown to anidb at the time of the last check.) | |||
Later versions of the API might enforce this by banning clients which ask for the same information more than once every week/month. | |||
=== Tag option === | === Tag option === | ||
The api will add a user defined string at the beginning of each reply line seperated with a space, if desired. | The api will add a user defined string at the beginning of each reply line seperated with a space, if desired. | ||
To enable | * To enable add the <tt>tag={str usertag}</tt> option to a command. | ||
A tag is only valid for the command it was send with, meaning it is not persistent | * A tag is only valid for the command it was send with, meaning it is not persistent. If you want to have tags in front of all reply lines you will have to append the tag option to each command you send to the server. | ||
Tags are ment to enable a client to handle more than one request/reply at a time. | * Tags are ment to enable a client to handle more than one request/reply at a time. | ||
Usage example: | Usage example: | ||
| Line 140: | Line 136: | ||
{{eyecatch|NOTE:| The tag option is valid for all api commands and is thus not explicitly listed in the description of each command.}} | {{eyecatch|NOTE:| The tag option is valid for all api commands and is thus not explicitly listed in the description of each command.}} | ||
=== Data Indexes (fid,aid,eid,gid,lid) === | |||
=== | * All indexes start at 1 (not 0). | ||
* It is possible for table entries to have id fields with a value of 0 (i.e. gid). Those are to be interpreted as "NONE" or "NULL". | |||
* An ID is '''never''' reused. That means after an entry is deleted no new entry will ever have that ID again. | |||
( | |||
== Authing Commands == | == Authing Commands == | ||