UDP API Definition: Difference between revisions

'''Version:''' 0.03.188 (2009-04-24)<br>

* If you want to create a client you have to register it [http://anidb.net/perl-bin/animedb.pl?show=client here] and [[UDP_Clients|here]].

* If you have suggestions for improvements or new features use the [[UDP_API_DEV|development]] page.

* Please also take a look at the [[API|API]] page.

** Content newlines are encoded as &lt;br /&gt;, ' is encoded as ` and | is not allowed in data fields.

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 readable 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).

{{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:|

* '''Server:''' api.anidb.info

* 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!}}

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!)

'''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.

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).

** A Client MUST NOT send more than 0.5 packets per second.

** A Client MUST NOT send more than one packet every 30 seconds over an extended amount of time.

{{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:|

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).

{{eyecatch|NOTE:| The tag option is valid for all api commands and is thus not explicitly listed in the description of each command.}}

* 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".  

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

* AUTH user={str username}&pass={str password}&protover={int4 apiversion}&client={str clientname}&clientver={int4 clientversion}[&nat=1&comp=1&enc={str encoding}&mtu{int4 mtu value}]

{{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:| A frontend shall expect 501 and 502 messages to be returned on ANY command.}}

{{eyecatch|NOTE:| AniDB usernames are always lowercase and may only contain characters (a-z) and numbers (0-9).}}

* The clientname shall be a lowercase string containing only the chars ''a-z'' of ''4-16 chars'' length which identifies the client. (i.e. mykickassclient)

{{eyecatch|IMPORTANT:|

* DO NOT use the clientname of another existing client.

{{eyecatch|IMPORTANT:|

: (NOTE: 504 means that this version of the client is banned, not the user!)

{{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.  

* Default [http://en.wikipedia.org/wiki/MTU_(networking) ''MTU''] is 1400. Minimum allowed is 400, maximum 1400, due [http://en.wikipedia.org/wiki/Point-to-Point_Protocol_over_Ethernet PPPoE].

* A logout should ALWAYS be issued if the client is currently logged in and is either exiting or not expecting to send/receive any anidb api packets for the next >= 30 minutes.

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.

* ''API Password'' is the one defined in the profile settings [http://anidb.info/perl-bin/animedb.pl?show=profile page].

* The encryption key is md5(api_password_of_user+''salt'').

{{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.}}

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.

* Listen for 271-274 NOTIFICATIONs ('''not 290''').

====Notification Packet Format====

* date is the time of the event (in seconds since 1.1.1970)

* reltype is: 1 = anime, 2 = group, 3 = producer

* priority is: 0 = low, 1 = medium, 2 = high

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

'''New Private Message Notify:'''

* type is the type of the message (0=normal msg, 1=annonymous, 2=system msg, 3=mod msg)

* date is the time the message was sent (in seconds since 1.1.1970)

'''Buddy Event Notify:'''

  {int4 buddy uid}|{int2 event type}

* Possible event types:

** 1 => LOGOUT

** 2 => ACCEPTED

'''Going Down Event Notify:'''

* Only one datagram will be sent, and the server will not listen for replies.

Used to acknowledge notification packets (271-274). A client must be prepared to issue this command before using '''PUSH'''.

 

'''Command String:'''

* PUSHACK nid={int4 notify_packet_id}

 

* 280 PUSHACK CONFIRMED

* 380 NO SUCH PACKET PENDING

* See: '''PUSH'''

 

=== NOTIFY: Notifications ===

Get number of pending notifications (and number of online buddies).

 

'''Command String:'''

* NOTIFY [buddy=1]

 

'''Possible Replies:'''

: {int4 pending_file_notifications}|{int4 number_of_unread_messages}

when ''buddy=1''

* 290 NOTIFICATION

: {int4 pending_file_notifications}|{int4 number_of_unread_messages}|{int4 number_of_online_buddies}

 

'''Info:'''

* 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.

=== NOTIFYLIST: List Notification/Message IDs ===

List id of all pending (not acknowledged) ''new private message'' and ''new file'' notifications. Buddy events are not acknowledgeable.

* NOTIFYLIST

'''Possible Replies:'''

*291 NOTIFYLIST

: {str type}|{int4 id}

=== NOTIFYGET: Get Notification/Message ===

'''Command String:'''

* NOTIFYGET type={str type}&id={int4 id}

: {int4 id}|{int4 from_user_id}|{str from_user_name}|{int4 date}|{int4 type}|{str title}|{str body}

: {int4 relid}|{int4 type}|{int2 count}|{int4 date}|{str relidname}|{str fids}

=== NOTIFYACK: Acknowledge Notification/Message ===

This command will mark a message read or clear a ''new file'' notification. Buddy events are not acknowledgeable.

* NOTIFYACK type={str type}&id={int4 id}

when type = M

* 281 NOTIFYACK SUCCESSFUL

* 381 NO SUCH ENTRY

* 282 NOTIFYACK SUCCESSFUL

* 382 NO SUCH ENTRY

'''Info:'''

* type is:

'''Command String:'''

* BUDDYADD uid={int4 buddy uid}

* BUDDYADD uname={int4 buddy name}

'''Possible Replies:'''

* BUDDYDEL uid={int4 buddy uid}

* 356 NO SUCH BUDDY

=== BUDDYDENY: Deny user as Buddy ===

'''Command String:'''

* BUDDYDENY uid={int4 buddy uid}

'''Command String:'''

* BUDDYLIST startat={int2 start at #}

* 253 {int2 start} {int2 end} {int2 total} BUDDY LIST

: {int4 uid}|{str username}|{int2 state}

* state is a 16bit bit field in integer notation (lowest bit first):

  * bit 1 = this user is in your buddylist

=== BUDDYSTATE: Retrieve Buddy States===

'''Command String:'''

* BUDDYSTATE startat={int2 start at #}

* onlinestate is a 16bit bit field in integer notation (lowest bit first):

  * bit 1 = http online (user has issued a HTTP request within the last 10 minutes)

== Data Commands ==

* 230 ANIME

* 330 NO SUCH ANIME

'''Info:'''

* Fields are returned in the same order they appear in the ''amask'' field list: byte 1, bit 7 first

* Synonyms and short names are separated with '

* Category fields are separated with ',' and ordered by weight (desc).

* By name: must be perfect match of romaji/kanji/english/other/synonym/short name.

* NOTE: The category list is the first data to be truncated if needed. And then: synonym list, short name list. This applies to the FILE command too.

<table border="0" cellpadding="0" cellspacing="2">

<tr><td colspan="5" align="center">'''amask'''</td></tr>

  <td align="center">'''Byte 1'''</td>

  <td align="center">'''Byte 2'''</td>

  <td align="center">'''Byte 3'''</td>

  <td align="center">'''Byte 4'''</td>

  <td align="center">'''Byte 5'''</td>

   <td>

    <td>'''Bit'''</td>

    <td align="right">'''Dec'''</td>

    <td>'''Data Field'''</td>

    <tr bgcolor="#eee">

    <td>7</td>

    <td align="right">128</td>

    <td>6</td>

    <td align="right">64</td>

    <tr bgcolor="#eee">

    <td>5</td>

    <td align="right">32</td>

    <td>str year</td>

    </tr>

    <tr>

    <td align="right">16</td>

    <td>str type</td>

    </tr>

    <tr bgcolor="#eee">

    <td>3</td>

    <td align="right">8</td>

    </tr>

    <td>2</td>

    <td align="right">4</td>

    <td>str related aid type</td>

    </tr>

    <tr bgcolor="#eee">

    <td>1</td>

    <td align="right">2</td>

    <td>str category list</td>

    </tr>

    <td>0</td>

    <td align="right">1</td>

    <td>str category weight list</td>

    </tr>

  </table>

  </td>

     <td>'''Bit'''</td>

     <td align="right">'''Dec'''</td>

     <td>'''Data Field'''</td>

     <tr>

     <td>str romaji name</td>

     <tr bgcolor="#eee">

     <td>str kanji name</td>

     <tr>

     <td>str english name</td>

     <tr bgcolor="#eee">

     <td>str other name</td>

     <tr>

     <td>str short name list</td>

     <tr bgcolor="#eee">

     <td>str synonym list</td>

     <tr>

     <tr bgcolor="#eee">

     <td>'''Bit'''</td>

     <td align="right">'''Dec'''</td>

     <td>'''Data Field'''</td>

     <tr bgcolor="#eee">

     <td>int4 episodes</td>

     <tr>

     <td>int4 normal ep count</td>

     <tr bgcolor="#eee">

     <td>int4 special ep count</td>

     <tr>

     <td>int4 air date</td>

     <tr bgcolor="#eee">

     <td>int4 end date</td>

     <tr>

     <td>str url</td>

     <tr bgcolor="#eee">

     <td>str picname</td>

     <tr>

     <td>str category id list</td>

     <td>'''Bit'''</td>

     <td align="right">'''Dec'''</td>

     <td>'''Data Field'''</td>

     <tr>

     <td>int4 rating</td>

     <tr bgcolor="#eee">

     <td>int4 vote count</td>

     <tr>

     <td>int4 temp rating</td>

     <tr bgcolor="#eee">

     <td>int4 temp vote count</td>

     <tr>

     <td>int4 average review rating</td>

     <tr bgcolor="#eee">

     <td>int4 review count</td>

     <tr>

     <td>str award list</td>

     <tr bgcolor="#eee">

     <td>bool is 18+ restricted</td>

     <td>'''Bit'''</td>

     <td align="right">'''Dec'''</td>

     <td>'''Data Field'''</td>

     <tr bgcolor="#eee">

     <td>int4 anime planet id</td>

     <tr>

     <td>int4 ANN id</td>

     <tr bgcolor="#eee">

     <td>int4 allcinema id</td>

     <tr>

     <td>str AnimeNfo id</td>

     <tr bgcolor="#eee">

     <td>unused</td>

     <tr>

     <td>unused</td>

     <tr bgcolor="#eee">

     <td>unused</td>

     <tr>

     <td>int4 date record updated</td>

</tr>

</table>

 

=== ANIMEDESC: Retrieve Anime Description ===

'''Command String:'''<br>

* ANIMEDESC aid={int4 id}&part={int4 partno}

 

 

 

 

  > ANIMEDESC aid=3169&part=0&s=xxxxx

  < 233 ANIMEDESC

     0|1|As summer break arrives for the students, Jun Sakurada is busily studying on his own in the library, making up for time lost <cut>

 

=== EPISODE: Retrieve Episode Data ===

'''Command String:'''<br>

* EPISODE eid={int4 eid}

* EPISODE aname={str anime name}&epno={int4 episode number}

 

 

 

  > EPISODE eid=1&s=xxxxx

  < 240 EPISODE

 

   > EPISODE aname=Seikai no Monshou&epno=2&s=xxxxx

   < 240 EPISODE

 

=== FILE: Retrieve File Data ===

'''Command String:'''<br>

* FILE fid={int4 id}&fmask={hexstr fmask}&amask={hexstr amask}

* FILE size={int8 size}&ed2k={str ed2khash}&fmask={hexstr fmask}&amask={hexstr amask}

* FILE aid={int4 anime id}&gid={int4 group id}&epno={int4 episode number}&fmask={hexstr fmask}&amask={hexstr amask}

 

: {int4 fid}|...(data list)

 

* 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.

 

<pre>

bit / int value meaning

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)

4 / 8 FILE_ISV3: file is version 3

5 / 16 FILE_ISV4: file is version 4

6 / 32 FILE_ISV5: file is version 5

7 / 64 FILE_UNC: file is uncensored

8 / 128 FILE_CEN: file is censored

 

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 ==== 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 ==== 8 ==> FILE_ISV3 ==> file was not crc checked and is version 3

</pre>

 

<table border="0" cellpadding="0" cellspacing="2">

<tr><td colspan="4" align="center">'''fmask:'''</td></tr>

<tr>

  <td align="center">'''Byte 1'''</td>

  <td align="center">'''Byte 2'''</td>

  <td align="center">'''Byte 3'''</td>

  <td align="center">'''Byte 4'''</td>

</tr>

<tr>

   <td>

   <table>

     <tr>

     <td>'''Bit'''</td>

     <td align="right">'''Dec'''</td>

     <td>'''Data Field'''</td>

     </tr>

     <tr bgcolor="#eee">

     <td>7</td>

     <td align="right">128</td>

     <td>unused</td>

     </tr>

     <tr>

     <td>int4 aid</td>

     <tr bgcolor="#eee">

     <td>int4 eid</td>

     <td>int4 gid</td>

     <tr bgcolor="#eee">

     <td>int4 lid</td>

     <td>list other episodes</td>

     <tr bgcolor="#eee">

     <td>int2 IsDeprecated</td>

     <td>int2 state</td>

  <td>

  <table>

    <td>'''Bit'''</td>

     <td align="right">'''Dec'''</td>

     </tr>

     <tr>

     <td>7</td>

     <td align="right">128</td>

     <td>int8 size</td>

     <td>6</td>

     <td align="right">64</td>

     <td>str ed2k</td>

     <td>5</td>

     <td align="right">32</td>

    <td>str md5</td>

    <td>4</td>

    <td align="right">16</td>

    <td>str sha1</td>

     </tr>

    <td align="right">8</td>

    <td>str crc32</td>

    <tr bgcolor="#eee">

    <td>0</td>

    <td align="right">1</td>

    </tr>

  </table>

    <td>'''Bit'''</td>