AniDB

UDP API Definition: Difference between revisions

Page Discussion

UDP API Definition (view source)

Revision as of 08:45, 25 April 2009

2 bytes removed ,  25 April 2009
m
no edit summary
mNo edit summary
Line 58: Line 58:
*** 506 INVALID SESSION
*** 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|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.}}<br>


{{eyecatch|NOTE:|
{{eyecatch|Note|
While in daily maintenance the AniDB API will reply with
While in daily maintenance the AniDB API will reply with


Line 78: Line 78:
* Possible codes are 600-699.
* Possible codes are 600-699.
* Occurrences of these errors (except 601) should be reported to [[User:Ommina|Ommina]].
* Occurrences of these errors (except 601) should be reported to [[User:Ommina|Ommina]].
{{eyecatch|NOTE:| 6XX messages do not always return the tags given with the command which caused the error!}}
{{eyecatch|Note|6XX messages do not always return the tags given with the command which caused the error!}}


=== Connection Problems ===
=== Connection Problems ===
Line 85: Line 85:


=== 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/debugging!)


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:'''<br/>
'''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). 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.
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.


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).
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).
Line 105: Line 105:
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.


{{eyecatch|NOTE:| Dropped packets are still taken into account for the packet rate. Meaning if you continuously send packets your client will be banned forever.}}
{{eyecatch|Note|Dropped packets are still taken into account for the packet rate. Meaning if you continuously send packets your client will be banned forever.}}


Generally clients should be written in a way to minimize server and network load. You should always keep that in mind.
Generally clients should be written in a way to minimize server and network load. You should always keep that in mind.
Line 111: Line 111:
Abusive clients may be banned completely.
Abusive clients may be banned completely.


{{eyecatch|NOTE:|
{{eyecatch|Note|
If you suddenly stop getting replies from the AniDB API or you normally don't have a notable packetloss and from one point on you suddenly note a high packetloss percentage you have most likely entered a critical flood ratio.
If you suddenly stop getting replies from the AniDB API or you normally don't have a notable packetloss and from one point on you suddenly note a high packetloss percentage you have most likely entered a critical flood ratio.
If the AniDB API isn't answering at all it might either be down or you have been banned, this is normally caused by violating the API specs (i.e. too many connections using different ports from one ip, too many auth failures, ...) (usually lasts 30 minutes).
If the AniDB API isn't answering at all it might either be down or you have been banned, this is normally caused by violating the API specs (i.e. too many connections using different ports from one IP, too many auth failures, ...) (usually lasts 30 minutes).
If you're experiencing packet loss you have probably reached the rate limit and the API starts to randomly drop incoming packets from your IP. (can be solved by enforcing a delay between multiple commands when you're sending a batch)}}
If you're experiencing packet loss you have probably reached the rate limit and the API starts to randomly drop incoming packets from your IP. (can be solved by enforcing a delay between multiple commands when you're sending a batch)}}


Line 140: Line 140:
   byebye 203 LOGGED OUT
   byebye 203 LOGGED OUT


{{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) ===
=== Data Indexes (fid,aid,eid,gid,lid) ===
* All indexes start at 1 (not 0).
* 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".  
* 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.
* An ID is '''never''' reused. That means after an entry is deleted no new entry will ever have that ID again.
* Mylist IDs (lid) are globally unique, not per-user unique.
* Mylist IDs (lid) are globally unique, not per-user unique.


== Authing Commands ==
== Authing Commands ==
{{eyecatch|NOTE:| '''ANY''' command which requires parameters may return: 505 ILLEGAL INPUT OR ACCESS DENIED}}
{{eyecatch|Note|'''ANY''' command which requires parameters may return: 505 ILLEGAL INPUT OR ACCESS DENIED}}


----
----
Line 169: Line 169:


'''Info:'''
'''Info:'''
{{eyecatch|NOTE:|The password is the normal AniDB website password! The password listed in the profile as API Password in only used for the optional encryption feature.}}
{{eyecatch|Note|The password is the normal AniDB website password! The password listed in the profile as API Password in only used for the optional encryption feature.}}
* The ''session_key'' is a String containing only ''a-z,A-Z,0-9'' chars of a length of ''4-8'' characters.
* The ''session_key'' is a String containing only ''a-z,A-Z,0-9'' chars of a length of ''4-8'' characters.
: It has to be stored by the client and needs to be sent as parameter with every command which requires the user to logged in.
: It has to be stored by the client and needs to be sent as parameter with every command which requires the user to logged in.
Line 178: Line 178:
* A '''503 CLIENT VERSION OUTDATED''' message states that the udp server has been updated and does not support your client any longer. (protover is too low). A 201 message refers to a new version of the client software.
* A '''503 CLIENT VERSION OUTDATED''' message states that the udp server has been updated and does not support your client any longer. (protover is too low). A 201 message refers to a new version of the client software.
* A '''506 INVALID SESSION''' means that either the session key parameter "s" was not provided with a command that requires it or the session key is no longer valid. The client should reissue an AUTH command.
* A '''506 INVALID SESSION''' means that either the session key parameter "s" was not provided with a command that requires it or the session key is no longer valid. The client should reissue an AUTH command.
{{eyecatch|NOTE:| A frontend shall expect 501 and 502 messages to be returned on ANY command.}}
{{eyecatch|Note|A frontend shall expect 501 and 502 messages to be returned on ANY command.}}<br>
{{eyecatch|NOTE:| AniDB usernames are always lowercase and may only contain characters (a-z) and numbers (0-9).}}
{{eyecatch|Note|AniDB usernames are always lowercase and may only contain characters (a-z) and numbers (0-9).}}
* The client should silently convert all entered usernames to lowercase before sending them to the API.
* The client should silently convert all entered usernames to lowercase before sending them to the API.
* The client should send the apiversion of the AnimeDB API version it supports as value of the protover parameter.
* The client should send the apiversion of the AnimeDB API version it supports as value of the protover parameter.
Line 187: Line 187:
* The clientversion shall be a number starting with 1, increased on every change in the client.
* The clientversion shall be a number starting with 1, increased on every change in the client.
: clientname and clientversion might be used by the API to distinguish between different clients and client versions if that should ever become necessary.
: clientname and clientversion might be used by the API to distinguish between different clients and client versions if that should ever become necessary.
{{eyecatch|IMPORTANT:|
{{eyecatch|Important|
* DO NOT use the clientname of another existing client.
* DO NOT use the clientname of another existing client.
* ALWAYS increase the clientversion number if you release a new client version.}}
* ALWAYS increase the clientversion number if you release a new client version.}}
Line 195: Line 195:
* If the client does not use any of the notification/push features of the API it should NOT keep the connection alive, furthermore it should explicitly terminate the connection by issuing a LOGOUT command once it finished it's work.
* If the client does not use any of the notification/push features of the API it should NOT keep the connection alive, furthermore it should explicitly terminate the connection by issuing a LOGOUT command once it finished it's work.
* If it is very likely that another command will be issued shortly (within the next 20 minutes) a client SHOULD keep the current connection open, by not sending a LOGOUT command.
* If it is very likely that another command will be issued shortly (within the next 20 minutes) a client SHOULD keep the current connection open, by not sending a LOGOUT command.
{{eyecatch|IMPORTANT:|
{{eyecatch|Important|
* A client should NOT perform a full AUTH / command / LOGOUT cycle for each command it wants to send.  Again, if another command is likely within 20 minutes, remain logged in.}}
* A client should NOT perform a full AUTH / command / LOGOUT cycle for each command it wants to send.  Again, if another command is likely within 20 minutes, remain logged in.}}
* The client shall notify the user if it received a 201 message at login.
* The client shall notify the user if it received a 201 message at login.
Line 202: Line 202:
: (NOTE: 504 means that this version of the client is banned, not the user!)
: (NOTE: 504 means that this version of the client is banned, not the user!)
* The 'nat' option makes the client able to detect whether it is behind a nat router or not. When the client is behind a nat router it should keep the "connection" alive with the PING command.
* The 'nat' option makes the client able to detect whether it is behind a nat router or not. When the client is behind a nat router it should keep the "connection" alive with the PING command.
{{eyecatch|IMPORTANT:|Make sure your client handles ALL possible AUTH return codes before giving out any versions!}}
{{eyecatch|Important|Make sure your client handles ALL possible AUTH return codes before giving out any versions!}}
* When ''enc=x'' is defined the server will change the encoding used to x.  
* When ''enc=x'' is defined the server will change the encoding used to x.
**If the encoding is supported it will change right away (including the response) and be reset on logout/timeout.
**If the encoding is supported it will change right away (including the response) and be reset on logout/timeout.
**If not supported then the argument will be silently ignored. Use ENCODING to test what works.
**If not supported then the argument will be silently ignored. Use ENCODING to test what works.
Line 279: Line 279:
* Use NOTIFYACK to acknowledge a notification, supplying the ID provided by NOTIFYLIST (if desired)
* Use NOTIFYACK to acknowledge a notification, supplying the ID provided by NOTIFYLIST (if desired)


{{eyecatch|NOTE|The ID supplied by NOTIFYLIST will be the ID of the affected notification type.  Since, at present, only the anime type is supported, this value is always an aid.  In the future, it may represent a group or producer ID.  In these cases, the str '''type''' value will indicate what entity the ID represents.}}
{{eyecatch|Note|The ID supplied by NOTIFYLIST will be the ID of the affected notification type.  Since, at present, only the anime type is supported, this value is always an aid.  In the future, it may represent a group or producer ID.  In these cases, the str '''type''' value will indicate what entity the ID represents.}}


'''Method Two: Server PUSH'''
'''Method Two: Server PUSH'''


With this method, the server takes the active role in advising the client that a new file has arrived.  The client must register with the server to receive these advisements, and will be responsible for keeping the login session from timing out, and any NAT router ports open.  The UDP packet is sent to the ip and port from which the AUTH command was received.
With this method, the server takes the active role in advising the client that a new file has arrived.  The client must register with the server to receive further advice information, and will be responsible for keeping the login session from timing out, and any NAT router ports open.  The UDP packet is sent to the ip and port from which the AUTH command was received.


This method compensates for the disadvantages of the polling method, but is more difficult to code.  Blocking sockets are no longer an option, nor can a client make any assumptions that an incoming packet will necessarily be a reply to the last command sent.  The tag option may be helpful here.
This method compensates for the disadvantages of the polling method, but is more difficult to code.  Blocking sockets are no longer an option, nor can a client make any assumptions that an incoming packet will necessarily be a reply to the last command sent.  The tag option may be helpful here.
Line 329: Line 329:
* priority is: 0 = low, 1 = medium, 2 = high
* priority is: 0 = low, 1 = medium, 2 = high


{{eyecatch|NOTE| Group (and producer) related file notifications are not implemented yet.}}
{{eyecatch|Note|Group (and producer) related file notifications are not implemented yet.}}


'''New Private Message Notify:'''
'''New Private Message Notify:'''
Line 392: Line 392:
* If the client did send a NOTIFY within the last 35 minutes and it was confirmed by AniDB then receiving a 501 LOGIN FIRST message for the next NOTIFY command shows that AniDB logged the client out because it did not respond to a PUSH Notification packet.
* If the client did send a NOTIFY within the last 35 minutes and it was confirmed by AniDB then receiving a 501 LOGIN FIRST message for the next NOTIFY command shows that AniDB logged the client out because it did not respond to a PUSH Notification packet.
* There is no command to retrieve missed PUSH Notifications.
* There is no command to retrieve missed PUSH Notifications.
{{eyecatch|NOTE| This command MUST NOT be issued more than once every 20 minutes.}}
{{eyecatch|Note|This command MUST NOT be issued more than once every 20 minutes.}}


----
----
=== NOTIFYLIST: List Notification/Message IDs ===
=== NOTIFYLIST: List Notification/Message IDs ===
List id of all pending (not acknowledged) ''new private message'' and ''new file'' notifications. Buddy events are not acknowledgeable.
List id of all pending (not acknowledged) ''new private message'' and ''new file'' notifications. Buddy events cannot be acknowledged.


'''Command String:'''
'''Command String:'''
Line 413: Line 413:
* id is the identifier for the notification/message as required by NOTIFYGET. For messages it is the actual message id, for notifications it is the id of the related type; anime, group or producer. Since only file notifications related to anime is implemented atm, it is the anime id (aid).
* id is the identifier for the notification/message as required by NOTIFYGET. For messages it is the actual message id, for notifications it is the id of the related type; anime, group or producer. Since only file notifications related to anime is implemented atm, it is the anime id (aid).
* NOTIFYLIST returns one line per entry, if no entries are available only the first line of the reply is returned.
* NOTIFYLIST returns one line per entry, if no entries are available only the first line of the reply is returned.
{{eyecatch|NOTE| This command MUST NOT be issued regularly but should only be triggered by either a push message received by the client or a reply to a NOTIFY command which tells you that there are messages/notifications waiting.}}
{{eyecatch|Note|This command MUST NOT be issued regularly but should only be triggered by either a push message received by the client or a reply to a NOTIFY command which tells you that there are messages/notifications waiting.}}


----
----
Line 888: Line 888:


'''Info:'''
'''Info:'''
* fid, aid, eid, gid are the unique ids for the file, anime, ep, group entries at anidb.
* fid, aid, eid, gid are the unique ids for the file, anime, ep, group entries at AniDB.
: You can use those to create links to the corresponding pages at anidb.
: You can use those to create links to the corresponding pages at AniDB.
* anidbfilename is the anidb filename for the file.
* anidbfilename is the AniDB filename for the file.
: However this name does not contain all the extra information of the filenames on AniDB and might be composed slightly different.
: However this name does not contain all the extra information of the filenames on AniDB and might be composed slightly different.
* fmask and amask are hexidecimal strings where each bit corresponds to a data field related to the specified file (see below). The data list received is sorted in the same order as the tables (and fmask before amask).  There is '''no''' provision to retrieve all fields.  Further, requesting a 'unusued' or 'reserved' bit will return an "illegal input" error.
* fmask and amask are hexidecimal strings where each bit corresponds to a data field related to the specified file (see below). The data list received is sorted in the same order as the tables (and fmask before amask).  There is '''no''' provision to retrieve all fields.  Further, requesting a 'unusued' or 'reserved' bit will return an "illegal input" error.
Line 898: Line 898:
<pre>
<pre>
bit / int value meaning
bit / int value meaning
1 / 1 FILE_CRCOK: file matched official crc (displayed with green background in anidb)
1 / 1 FILE_CRCOK: file matched official CRC (displayed with green background in anidb)
2 / 2 FILE_CRCERR: file DID NOT match official crc (displayed with red background in anidb)
2 / 2 FILE_CRCERR: file DID NOT match official CRC (displayed with red background in anidb)
3 / 4 FILE_ISV2: file is version 2
3 / 4 FILE_ISV2: file is version 2
4 / 8 FILE_ISV3: file is version 3
4 / 8 FILE_ISV3: file is version 3
Line 908: Line 908:


examples:
examples:
state ==== 9 ==> FILE_CRCOK+FILE_ISV3 ==> file matched official crc and is version 3
state ==== 9 ==> FILE_CRCOK+FILE_ISV3 ==> file matched official CRC and is version 3
state ==== 0 ==> - ==> file was not crc checked and is version 1
state ==== 0 ==> - ==> file was not crc checked and is version 1
state ==== 34 ==> FILE_CRCERR+FILE_ISV5 ==> file DID NOT match official crc and is version 5
state ==== 34 ==> FILE_CRCERR+FILE_ISV5 ==> file DID NOT match official CRC and is version 5
state ==== 1 ==> FILE_CRCOK ==> file matched official crc and is version 1
state ==== 1 ==> FILE_CRCOK ==> file matched official CRC and is version 1
state ==== 8 ==> FILE_ISV3 ==> file was not crc checked and is version 3
state ==== 8 ==> FILE_ISV3 ==> file was not CRC checked and is version 3
</pre>
</pre>


Line 1,405: Line 1,405:


'''Info:'''
'''Info:'''
* The state field provides information about the location and sharing state of a file in mylist.
* The state field provides information about the location and sharing state of a file in MyList.
* If files are added after hashing, a client should specify the state as 1 (on hdd) (if the user doesn't explicitly select something else).
* If files are added after hashing, a client should specify the state as 1 (on HDD) (if the user doesn't explicitly select something else).
* eps is a list of episodes, e.g. "1-12,14-16,T1"
* eps is a list of episodes, e.g. "1-12,14-16,T1"


Line 1,666: Line 1,666:
'''Note:'''
'''Note:'''
* This command allows you to send an AniDB message.
* This command allows you to send an AniDB message.
{{eyecatch|IMPORTANT:|
{{eyecatch|Important|
title must not be longer than 50 chars.
title must not be longer than 50 chars.<br>
body must not be longer than 900 chars.
body must not be longer than 900 chars.
}}
}}
Line 1,729: Line 1,729:


== Return Codes ==
== Return Codes ==
Note: The names below do _not_ necessarily reflect the actual code strings returned by the server.  
Note: The names below do '''not''' necessarily reflect the actual code strings returned by the server.
<pre>
<pre>
// POSITIVE 2XX
// POSITIVE 2XX
Foo2
1,633

edits

Retrieved from "https://wiki.anidb.net/Special:MobileDiff/12334"
MediaWiki spam blocked by CleanTalk.
MediaWiki spam blocked by CleanTalk.