AniDB

UDP API Definition: Difference between revisions

Page Discussion

UDP API Definition (view source)

Revision as of 04:09, 22 April 2009

49 bytes removed ,  22 April 2009
m
no edit summary
mNo edit summary
Line 33: Line 33:


== Basics ==
== Basics ==
=== General ===
=== General ===
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 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).
Line 66: Line 65:
601 ANIDB OUT OF SERVICE - TRY AGAIN LATER
601 ANIDB OUT OF SERVICE - TRY AGAIN LATER


to all commands. If a client recieves such a return value it should wait at least 30 minutes before trying again.
to all commands. If a client recieves such a return value it should wait at least 30 minutes before trying again.}}
}}


=== Server / UDP Connection ===
=== Server / UDP Connection ===
Line 74: Line 72:
* '''Port:''' 9000/UDP
* '''Port:''' 9000/UDP
The servername and port should not be hardcoded into a frontend but should be read from a configuration file.
The servername and port should not be hardcoded into a frontend but should be read from a configuration file.
=== Server Errors ===
=== Server Errors ===
* At any time the API might return a fatal error of the form:
* At any time the API might return a fatal error of the form:
Line 115: Line 114:
If you suddenly stop getting replies from the AniDB API or you normally don't have a noteable 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 noteable 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 vialoating 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 vialoating 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)}}
}}


=== Anti Leech Protection ===
=== Anti Leech Protection ===
Line 198: Line 196:
* 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 shout 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 shoud 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 recieved a 201 message at login.
* The client shall notify the user if it recieved a 201 message at login.
: This means a new version of the client is available, however the old version is still supported otherwise a client banned message would have been returned.
: This means a new version of the client is available, however the old version is still supported otherwise a client banned message would have been returned.
Line 215: Line 213:


----
----
=== LOGOUT: Logout ===
=== LOGOUT: Logout ===
'''Command String:'''
'''Command String:'''
Line 229: Line 226:


----
----
=== ENCRYPT: Start Encrypted Session ===
=== ENCRYPT: Start Encrypted Session ===
Will cause all future messages from the server, except the first (the reply to the ENCRYPT command itself), to be encrypted (128 bit [http://en.wikipedia.org/wiki/Advanced_Encryption_Standard AES]). The client will also have to encrypt all future requests sent to the server. All non-encrypted messages will be discarded by the server. The encryption key is the [http://en.wikipedia.org/wiki/MD5 MD5] hash of a special ''API Password'' (defined in the users profile) concatenated with the salt string as given in the reply to the ENCRYPT message. A normal AUTH message is still necessary to authenticate and should follow the ENCRYPT command once the API has acknowledged the encryption.
Will cause all future messages from the server, except the first (the reply to the ENCRYPT command itself), to be encrypted (128 bit [http://en.wikipedia.org/wiki/Advanced_Encryption_Standard AES]). The client will also have to encrypt all future requests sent to the server. All non-encrypted messages will be discarded by the server. The encryption key is the [http://en.wikipedia.org/wiki/MD5 MD5] hash of a special ''API Password'' (defined in the users profile) concatenated with the salt string as given in the reply to the ENCRYPT message. A normal AUTH message is still necessary to authenticate and should follow the ENCRYPT command once the API has acknowledged the encryption.
Line 253: Line 249:


== Notify Commands ==
== Notify Commands ==
=== Introduction ===
=== Introduction ===
Broadly speaking, notifications provide an indication to the client that some event has occurred within the AniDB database.
Broadly speaking, notifications provide an indication to the client that some event has occurred within the AniDB database.


Line 268: Line 262:


=== Getting Notifications ===
=== Getting Notifications ===
Clients that wish to receive notifications have two routes available to them.  They are by no means mutually exclusive and selecting one does not imply a client is unable to use commands from another.
Clients that wish to receive notifications have two routes available to them.  They are by no means mutually exclusive and selecting one does not imply a client is unable to use commands from another.


Line 285: Line 278:
* Use NOTIFYGET to receive a notification, suppling the ID provided by NOTIFYLIST
* Use NOTIFYGET to receive a notification, suppling the ID provided by NOTIFYLIST
* Use NOTIFYACK to acknowledge a notification, suppling the ID provided by NOTIFYLIST (if desired)
* Use NOTIFYACK to acknowledge a notification, suppling 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.}}
Line 303: Line 295:
* Use NOTIFYACK to acknowledge a notification, suppling the relid provided by NOTIFICATION (if desired)
* Use NOTIFYACK to acknowledge a notification, suppling the relid provided by NOTIFICATION (if desired)
* Use UPTIME (with an interval between 30 and 35 minutes) to keep login session valid
* Use UPTIME (with an interval between 30 and 35 minutes) to keep login session valid


It is probably a good idea to use tags to separate NOTIFICATIONs from the other communication. NOTIFICATIONs will '''never''' have tags.
It is probably a good idea to use tags to separate NOTIFICATIONs from the other communication. NOTIFICATIONs will '''never''' have tags.


=== PUSH: UDP Notification Registration ===
=== PUSH: UDP Notification Registration ===
Line 370: Line 360:
* The comment is a short explanation for the downtime.
* The comment is a short explanation for the downtime.
* Only one datagram will be sent, and the server will not listen for replies.
* Only one datagram will be sent, and the server will not listen for replies.
----
----
=== PUSHACK: UDP Notification Acknowledge ===
=== PUSHACK: UDP Notification Acknowledge ===
Used to acknowledge notification packets (271-274). A client must be prepared to issue this command before using '''PUSH'''.
Used to acknowledge notification packets (271-274). A client must be prepared to issue this command before using '''PUSH'''.
Line 405: Line 395:


----
----
=== 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 are not acknowledgeable.
Line 427: Line 416:


----
----
=== NOTIFYGET: Get Notification/Message ===
=== NOTIFYGET: Get Notification/Message ===
Receive private message or file notification.
Receive private message or file notification.
Line 459: Line 447:
: date is the time of the event (in seconds since 1.1.1970)
: date is the time of the event (in seconds since 1.1.1970)
: fids is a comma separated list with the affected file ids
: fids is a comma separated list with the affected file ids
----
----
=== NOTIFYACK: Acknowledge Notification/Message ===
=== NOTIFYACK: Acknowledge Notification/Message ===
This command will mark a message read or clear a ''new file'' notification. Buddy events are not acknowledgeable.
This command will mark a message read or clear a ''new file'' notification. Buddy events are not acknowledgeable.
Line 493: Line 481:


----
----
=== BUDDYDEL: Remove a user from Buddy List ===
=== BUDDYDEL: Remove a user from Buddy List ===
'''Command String:'''
'''Command String:'''
Line 502: Line 489:


----
----
=== BUDDYACCEPT: Accept user as Buddy ===
=== BUDDYACCEPT: Accept user as Buddy ===
'''Command String:'''
'''Command String:'''
Line 512: Line 498:


----
----
=== BUDDYDENY: Deny user as Buddy ===
=== BUDDYDENY: Deny user as Buddy ===
'''Command String:'''
'''Command String:'''
Line 522: Line 507:


----
----
=== BUDDYLIST: Retrieve Buddy List ===
=== BUDDYLIST: Retrieve Buddy List ===
'''Command String:'''
'''Command String:'''
Line 537: Line 521:


----
----
=== BUDDYSTATE: Retrieve Buddy States===
=== BUDDYSTATE: Retrieve Buddy States===
'''Command String:'''
'''Command String:'''
Line 832: Line 815:


----
----
=== ANIMEDESC: Retrieve Anime Description ===
=== ANIMEDESC: Retrieve Anime Description ===
'''Command String:'''<br>
'''Command String:'''<br>
Line 884: Line 866:


----
----
=== FILE: Retrieve File Data ===
=== FILE: Retrieve File Data ===
'''Command String:'''<br>
'''Command String:'''<br>
Line 1,141: Line 1,122:
  </tr>
  </tr>
</table>
</table>


<table border="0" cellpadding="0" cellspacing="2">
<table border="0" cellpadding="0" cellspacing="2">
Line 1,352: Line 1,332:


'''Examples:''' (html escaped code intended)
'''Examples:''' (html escaped code intended)
<pre>
  > FILE size=177747474&ed2k=70cd93fd3981cc80a8ea6a646ff805c9&fmask=7FF8FEF8&amask=C000F0C0&s=xxxxx
> FILE size=177747474&ed2k=70cd93fd3981cc80a8ea6a646ff805c9&fmask=7FF8FEF8&amask=C000F0C0&s=xxxxx
  < 220 FILE
< 220 FILE
  312498|4688|69260|4243|0||0|1|177747474|70cd93fd3981cc80a8ea6a646ff805c9|b2a7c7d591333e20495de3571b235c28|7af9b962c17ff729baeee67533e5219526cd5095|a200fe73|high|DTV|Vorbis (Ogg Vorbis)|104|H264/AVC|800|704x400|japanese|english'english'english|1560||1175472000|26|26|01|The Wings to the Sky|Sora he no Tsubasa|????|#nanoha-DamagedGoodz|Nanoha-DGz
312498|4688|69260|4243|0||0|1|177747474|70cd93fd3981cc80a8ea6a646ff805c9|b2a7c7d591333e20495de3571b235c28|7af9b962c17ff729baeee67533e5219526cd5095|a200fe73|high|DTV|Vorbis (Ogg Vorbis)|104|H264/AVC|800|704x400|japanese|english'english'english|1560||1175472000|26|26|01|The Wings to the Sky|Sora he no Tsubasa|????|#nanoha-DamagedGoodz|Nanoha-DGz
</pre>
 


----
----
=== GROUP: Retrieve Group Data ===
=== GROUP: Retrieve Group Data ===
'''Command String:'''<br>
'''Command String:'''<br>
Line 1,383: Line 1,359:


----
----
=== GROUPSTATUS: Get Completed Episode ===
=== GROUPSTATUS: Get Completed Episode ===
Returns a list of group names and ranges of episodes released by the group for a given anime.
Returns a list of group names and ranges of episodes released by the group for a given anime.
Line 1,459: Line 1,433:


----
----
=== MYLISTADD: Add file to mylist ===
=== MYLISTADD: Add file to mylist ===
The command string for MYLISTADD is made of up two blocks: a 'fileinfo' block, which limits the command to a specific file, or an 'animeinfo'/'groupinfo'/'episodeinfo' block, which can be used to specify a range of files, including generics.  Additionally, a number of optional parameters can be included with either set.
The command string for MYLISTADD is made of up two blocks: a 'fileinfo' block, which limits the command to a specific file, or an 'animeinfo'/'groupinfo'/'episodeinfo' block, which can be used to specify a range of files, including generics.  Additionally, a number of optional parameters can be included with either set.


'''Adding a single file to the MyList with the 'fileinfo' block'''
'''Adding a single file to the MyList with the 'fileinfo' block'''
Line 1,472: Line 1,443:
'''or'''
'''or'''
* MYLISTADD lid={int4 lid}&edit=1  (valid for edit only)
* MYLISTADD lid={int4 lid}&edit=1  (valid for edit only)


'''Adding one or more files to the MyList with the 'animeinfo'/'groupinfo'/'episodeinfo' block'''
'''Adding one or more files to the MyList with the 'animeinfo'/'groupinfo'/'episodeinfo' block'''


Here, you have a number of options, depending on what data you have available.  In brief, 'animeinfo' represents a choice between anime id and anime name.  'groupinfo' represents a choice between group id, group name, and generic=1.  'episodeinfo' represents a range of one or more episodes.
Here, you have a number of options, depending on what data you have available.  In brief, 'animeinfo' represents a choice between anime id and anime name.  'groupinfo' represents a choice between group id, group name, and generic=1.  'episodeinfo' represents a range of one or more episodes.


* MYLISTADD aid={int4 aid}&gid={int gid}&epno={int4 episode number}
* MYLISTADD aid={int4 aid}&gid={int gid}&epno={int4 episode number}
Line 1,490: Line 1,459:
'''or'''
'''or'''
* MYLISTADD aname={str anime_name}&generic=1&epno={int4 episode number}
* MYLISTADD aname={str anime_name}&generic=1&epno={int4 episode number}


Each command listed can have, in addition, a number of optional components to provide further MyList details.  Append these as desired.
Each command listed can have, in addition, a number of optional components to provide further MyList details.  Append these as desired.
Line 1,500: Line 1,468:
* &storage={str storage}
* &storage={str storage}
* &other={str other}
* &other={str other}


Finally, edit=1 can be included to edit a mylist entry instead of creating a new one.  When editing, optional values that are not supplied retain their original value.  That is, they are ''not'' replaced with default or empty values.  Only values supplied are updated.
Finally, edit=1 can be included to edit a mylist entry instead of creating a new one.  When editing, optional values that are not supplied retain their original value.  That is, they are ''not'' replaced with default or empty values.  Only values supplied are updated.
Line 1,534: Line 1,501:


----
----
=== MYLISTDEL: Remove file from mylist ===
=== MYLISTDEL: Remove file from mylist ===
'''Command String:'''<br>
'''Command String:'''<br>
Line 1,558: Line 1,524:


----
----
=== MYLISTSTATS : Retrieve mylist stats ===
=== MYLISTSTATS : Retrieve mylist stats ===
'''Command String:'''
'''Command String:'''
Line 1,570: Line 1,535:


----
----
=== VOTE: Vote for specified anime/episode/group ===
=== VOTE: Vote for specified anime/episode/group ===
'''Command String:'''<br>
'''Command String:'''<br>
Line 1,614: Line 1,578:


== Misc Commands ==
== Misc Commands ==
=== MYLISTEXPORT: Schedule a MyList Export ===
=== MYLISTEXPORT: Schedule a MyList Export ===
Queues a [http://anidb.net/perl-bin/animedb.pl?show=export MyList Export] by the AniDb Servers.  As with a manual export request, exports are only done during periods when server load is low.  As a result, exports may take up to 24 hours.  The client submitting the request will receive an AniDb message when the export is ready to be collected.
Queues a [http://anidb.net/perl-bin/animedb.pl?show=export MyList Export] by the AniDb Servers.  As with a manual export request, exports are only done during periods when server load is low.  As a result, exports may take up to 24 hours.  The client submitting the request will receive an AniDb message when the export is ready to be collected.
Line 1,636: Line 1,599:


----
----
=== PING: Ping Command ===
=== PING: Ping Command ===
'''Command String:'''
'''Command String:'''
Line 1,652: Line 1,614:


----
----
=== VERSION: Retrieve Server Version ===
=== VERSION: Retrieve Server Version ===
'''Command String:'''
'''Command String:'''
Line 1,665: Line 1,626:


----
----
=== UPTIME: Retrieve Server Uptime ===
=== UPTIME: Retrieve Server Uptime ===
'''Command String:'''
'''Command String:'''
Line 1,678: Line 1,638:


----
----
=== ENCODING: Change Encoding for Session ===
=== ENCODING: Change Encoding for Session ===
Sets preferred [http://en.wikipedia.org/wiki/Character_encoding encoding] per session. The preferred way to do this is to use the '''enc''' argument for AUTH. This command is mostly for testing.
Sets preferred [http://en.wikipedia.org/wiki/Character_encoding encoding] per session. The preferred way to do this is to use the '''enc''' argument for AUTH. This command is mostly for testing.
Line 1,713: Line 1,672:


----
----
=== USER: Retrieve User UID ===
=== USER: Retrieve User UID ===
'''Command String:'''
'''Command String:'''
Line 1,726: Line 1,684:


----
----
=== STATS [<span style="color:red">disabled</span>] ===
=== STATS [<span style="color:red">disabled</span>] ===
'''Command String:'''
'''Command String:'''
Line 1,736: Line 1,693:


----
----
=== TOP [<span style="color:red">disabled</span>] ===
=== TOP [<span style="color:red">disabled</span>] ===
'''Command String:'''
'''Command String:'''
Ninjamask
staff
2,096

edits

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