1,633
edits
mNo edit summary |
mNo edit summary |
||
Line 7: | Line 7: | ||
'''IMPORTANT INFORMATION FOR ALL INTERESTED:''' | '''IMPORTANT INFORMATION FOR ALL INTERESTED:''' | ||
* If you are mainly interested in notifications and private messaging, check out our [[Jabber]] and [[RSSRDF]] support first. | * If you are mainly interested in notifications and private messaging, check out our [[Jabber]] and [[RSSRDF]] support first. | ||
* The UDP API is not an appropriate choice if you desire to download a local copy of the | * The UDP API is not an appropriate choice if you desire to download a local copy of the AniDB database. | ||
* 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 want to create a client you have to register it [http://anidb.net/perl-bin/animedb.pl?show=client here] and [[UDP_Clients|here]]. | ||
** Check out the clients that are being developed. There exists usable code in many different languages already. | ** Check out the clients that are being developed. There exists usable code in many different languages already. | ||
Line 34: | Line 34: | ||
== 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 | 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). | ||
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 | 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 separated by a "|" character. | ||
<tt>{three digit return code} {str return string}\n</tt><br> | <tt>{three digit return code} {str return string}\n</tt><br> | ||
Line 65: | Line 65: | ||
601 ANIDB OUT OF SERVICE - TRY AGAIN LATER | 601 ANIDB OUT OF SERVICE - TRY AGAIN LATER | ||
to all commands. If a client | to all commands. If a client receives such a return value it should wait at least 30 minutes before trying again.}} | ||
=== Server / UDP Connection === | === Server / UDP Connection === | ||
Line 90: | Line 90: | ||
'''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 | 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 98: | Line 98: | ||
* Short Term: | * Short Term: | ||
** A Client MUST NOT send more than 0.5 packets per second. | ** 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 | ** The server will start to enforce the limit after the first 5 packets have been received. | ||
* Long Term: | * Long Term: | ||
** A Client MUST NOT send more than one packet every 30 seconds over an extended amount of time. | ** A Client MUST NOT send more than one packet every 30 seconds over an extended amount of time. | ||
Line 109: | Line 109: | ||
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. | ||
Abusive clients may be banned | 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 | 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 | 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 123: | Line 123: | ||
A client should locally cache FILE/EP/ANIME/GROUP/... info wherever possible for extended amounts of time. | 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 | (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. | 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 | The API will add a user defined string at the beginning of each reply line separated with a space, if desired. | ||
* To enable add the <tt>tag={str usertag}</tt> option to a command. | * 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. 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. | * 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 | * Tags are meant to enable a client to handle more than one request/reply at a time. | ||
Usage example: | Usage example: | ||
Line 176: | Line 176: | ||
* In case of a '''501 LOGIN FIRST''' message the client should silently resend an auth command and send the failed command again. | * In case of a '''501 LOGIN FIRST''' message the client should silently resend an auth command and send the failed command again. | ||
* A '''502 ACCESS DENIED''' message should abort the current action on the client side and display a message to the user. | * A '''502 ACCESS DENIED''' message should abort the current action on the client side and display a message to the user. | ||
* 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 | * 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.}} | ||
{{eyecatch|NOTE:| | {{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. | ||
* The client MAY NOT send anything but the version of the API Specs the author used to write the client! (as it is stated at the top of this file @ "Version number used for protover parameter") | * The client MAY NOT send anything but the version of the API Specs the author used to write the client! (as it is stated at the top of this file @ "Version number used for protover parameter") | ||
: The API will compare that value to it's own version of the API and if the version of the client is older the API will decide | : The API will compare that value to it's own version of the API and if the version of the client is older the API will decide whether the changes were significant enough to deny the old client access to the DB. | ||
* 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) | * 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) | ||
* 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 | : 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.}} | ||
* A Login and its assigned ''session_key'' is valid until the virtual UDP connection times out or until a LOGOUT command is issued. | * A Login and its assigned ''session_key'' is valid until the virtual UDP connection times out or until a LOGOUT command is issued. | ||
* The virtual UDP connection times out if no data was | * The virtual UDP connection times out if no data was received from the client for '''35 minutes'''. | ||
* A client should issue a UPTIME command once every 30 minutes to keep the connection alive should that be required. | * A client should issue a UPTIME command once every 30 minutes to keep the connection alive should that be required. | ||
* 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 | * 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 | * 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 | * The client shall notify the user if it received 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. | ||
* The user should get a | * The user should get a pop-up message on 503 and 504 messages telling him to update his client software. | ||
: (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 | {{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. | ||
Line 276: | Line 276: | ||
* Use NOTIFY (no more than once every 20 minutes) to get the number of pending notifications | * Use NOTIFY (no more than once every 20 minutes) to get the number of pending notifications | ||
* IF there are new notifications pending, use NOTIFYLIST to get a list of notification types and associated IDs. | * IF there are new notifications pending, use NOTIFYLIST to get a list of notification types and associated IDs. | ||
* Use NOTIFYGET to receive a notification, | * Use NOTIFYGET to receive a notification, supplying the ID provided by NOTIFYLIST | ||
* Use NOTIFYACK to acknowledge a notification, | * 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.}} | ||
Line 283: | Line 283: | ||
'''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 | 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. | ||
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 299: | Line 299: | ||
=== PUSH: UDP Notification Registration === | === PUSH: UDP Notification Registration === | ||
Register your client as an observer for | Register your client as an observer for AniDB notification events for the current user. If you are registered for one or more event types the AniDB server will send an UDP packet (format see below) on each change which affects the current user. | ||
'''Command String:''' | '''Command String:''' | ||
Line 310: | Line 310: | ||
'''Info:''' | '''Info:''' | ||
* A client which has registered to | * A client which has registered to receive UDP notification packets must: | ||
** Issue a PUSHACK command for each notification received with ''notify_packet_id'' provided in the notification packet. | ** Issue a PUSHACK command for each notification received with ''notify_packet_id'' provided in the notification packet. | ||
** Use PING to keep the connection alive (< 30 min). | ** Use PING to keep the connection alive (< 30 min). | ||
** Use UPTIME to ensure that the session is OK (>= 30 min). | ** Use UPTIME to ensure that the session is OK (>= 30 min). | ||
* Every notification generated is resent 3 times unless | * Every notification generated is resent 3 times unless acknowledged. After that the client is logged out. | ||
====Notification Packet Format==== | ====Notification Packet Format==== | ||
Line 357: | Line 357: | ||
* Clients with any notification on will receive the GOINGDOWN message before the API goes offline. | * Clients with any notification on will receive the GOINGDOWN message before the API goes offline. | ||
* Time offline is the time in minutes the API will be down, 0 if indefinite (client can direct user to the | * Time offline is the time in minutes the API will be down, 0 if indefinite (client can direct user to the AniDB site for status updates). | ||
* 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. | ||
Line 390: | Line 390: | ||
'''Info:''' | '''Info:''' | ||
* If the client did send a NOTIFY within the last 35 minutes and it was confirmed by AniDB then | * 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.}} | ||
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 | {{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 1,469: | Line 1,469: | ||
* &other={str other} | * &other={str other} | ||
Finally, edit=1 can be included to edit a | 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. | ||
'''Possible Replies:''' | '''Possible Replies:''' | ||
Line 1,496: | Line 1,496: | ||
* Other is the only field which may contain newlines, but they have to be stored as <br /> | * Other is the only field which may contain newlines, but they have to be stored as <br /> | ||
* For state values refer to: '''MYLIST''' | * For state values refer to: '''MYLIST''' | ||
* If you want to change an existing entry and already know its | * If you want to change an existing entry and already know its MyList id (lid) please use the lid-version of this command. It put less load on the server. | ||
* epno=0 means all eps (default), negative numbers means upto. (-12 -> upto 12) | * epno=0 means all eps (default), negative numbers means upto. (-12 -> upto 12) | ||
* group is optional only when edit=1, meaning you can't add every file for an anime | * group is optional only when edit=1, meaning you can't add every file for an anime | ||
Line 1,579: | Line 1,579: | ||
== 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 | 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. | ||
Only one export can be in the queue at a time. | Only one export can be in the queue at a time. | ||
Line 1,882: | Line 1,882: | ||
0.03 - 13.01.2006 | 0.03 - 13.01.2006 | ||
ANIME, EPISODE, GROUP, STATS, TOP, UPTIME, MYLISTSTATS, VOTE and RANDOM commands added | ANIME, EPISODE, GROUP, STATS, TOP, UPTIME, MYLISTSTATS, VOTE and RANDOM commands added | ||
it is now possible to use html escaped code in | it is now possible to use html escaped code in MyList fields, and '=' | ||
updated epno in default file name (for new specials) | updated epno in default file name (for new specials) | ||
... (a lot of stuff already forgotten) | ... (a lot of stuff already forgotten) |
edits