staff
2,096
edits
UDP API Definition: Difference between revisions
no edit summary
(→ANIME: Retrieve Anime Data: added "related aid type" values) |
No edit summary |
||
| Line 9: | Line 9: | ||
* 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 AniDB database. | * 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 | * If you want to create a client you have to register it {{AniDBLink|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. | ||
* If you have suggestions for improvements or new features use the [[ | * If you have suggestions for improvements or new features use the [[UDP API DEV|development]] page. | ||
* Please also take a look at the [[ | * Please also take a look at the [[API]] page. | ||
== Formats used in this Spec == | == Formats used in this Spec == | ||
| Line 35: | Line 35: | ||
== Basics == | == Basics == | ||
=== General === | === General === | ||
The network communication is ''packet'' and ''line'' based. Each | 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 separated by a "|" character. | 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. | ||
| Line 70: | Line 70: | ||
=== Server / UDP Connection === | === Server / UDP Connection === | ||
The Client has to send data packets to: | The Client has to send data packets to: | ||
* '''Server:''' api.anidb. | * '''Server:''' api.anidb.net | ||
* '''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. | ||
| Line 90: | Line 90: | ||
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 [ | '''Note when behind a [[Wikipedia: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. | ||
| Line 242: | Line 242: | ||
* ''user'' is the user name. | * ''user'' is the user name. | ||
* ''type'' is the type of encryption; 1 => 128 bit AES (only one defined). | * ''type'' is the type of encryption; 1 => 128 bit AES (only one defined). | ||
* ''API Password'' is the one defined in the profile settings | * ''API Password'' is the one defined in the {{AniDBLink|profile|profile settings page}}. | ||
* It is not possible to disable the encryption once enabled while staying logged in. | * It is not possible to disable the encryption once enabled while staying logged in. | ||
** A logout (the logout message needs to be correctly encrypted) or timeout will disable the encryption. | ** A logout (the logout message needs to be correctly encrypted) or timeout will disable the encryption. | ||