UDP API Definition: Difference between revisions

'''Version:''' 0.02c - 10.10.2004 <br>

'''Version number used for protover parameter:''' "2"

  0.02 - 13.08.2004

  FILE, MYLIST, MYLISTDEL, MYLISTADD commands added

  added NOTIFYLIST, NOTIFYGET, NOTIFYACK, SENDMSG commands

  0.01 - 10.08.2004

:: newlines are encoded as &lt;br&gt;, | is not allowed in data fields and ' is encoded as ´.  

The Client has to send data packets to:  

601 ANIDB OUT OF SERVICE - TRY AGAIN LATER  

:* Short Term:  

:* Long Term:  

At any time the API might return a fatal error of the form:  

:* 6xx ERROR DESCRIPTION  

== Commands ==

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

:* 200 {str session_key} LOGIN ACCEPTED  

:* 201 {str session_key} LOGIN ACCEPTED - NEW VERSION AVAILABLE  

:* 500 LOGIN FAILED  

:* 503 CLIENT VERSION OUTDATED  

:* 504 CLIENT BANNED - {str reason}  

:* 505 ILLEGAL INPUT OR ACCESS DENIED  

:* 601 ANIDB OUT OF SERVICE - TRY AGAIN LATER  

:* 501 LOGIN FIRST  

:* 502 ACCESS DENIED  

:* 506 INVALID SESSION  

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

:* The ''session_key'' String is appended as parameter "s", i.e. "PUSH notify=1&msg=1&s={str session_key}".

:* On a '''500 LOGIN FAILED''' message the client should request the user to enter username and password 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 '''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.

:* 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 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 wheter 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 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 nessecary.

:* DO NOT use the clientname of another existing client.

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

:* The virtual UDP connection times out if no data was recieved from the client for '''35 minutes'''.

:* A client should issue a NOTIFY 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 issueing 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 may keep the current connection open, until it times out on it's own, by not sending a LOGOUT command.

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

:* The user should get a popup 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!)

:* LOGOUT  

:* 203 LOGGED OUT

:* 403 NOT LOGGED IN  

:* This command only works if you are already logged in.

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

:* PUSH notify={bool push_file_added_notifications}&msg={bool push_msg_added_notifications}  

:* 270 NOTIFICATION ENABLED  

: OR (if both values are 0)  

:*370 NOTIFICATION DISABLED  

:* This command only works if you are logged in.

:* With this command you can register your client as an observer for anidb notification and message events for the current user. If you are registered for one or both events the anidb server will send an UDP packet (format see below) on each change which affects the current user. The UDP packet is sent to the ip and port from which the AUTH command was recieved.

:* UDP packets are resend 3 times, if the client does not acknowlege them. After that the client is logged out and no further notifies will be sent.

:* On recieving any of the above packets the client has to issue a PUSHACK command with the notify_packet_id provided in the notification packet.

:* File Added Notify:

   {int4 aid}|{int4 date}|{int4 count}|{str animetitle}  

:: aid is the id of the affected anime

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

:: count is the number of events pending for this anime

:: animetitle is the name of the affected anime

:* Message Added Notify:

   {int2 type}|{int4 date}|{int4 senderuid}|{str sendername}|{str subject}  

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

:: senderuid/sendername are the user id and username of the sender

:: subject is the message subject

:* PUSHACK nid={int4 notify_packet_id}  

:* 280 PUSHACK CONFIRMED

:* 380 NO SUCH PACKET PENDING

:* This command only works if you are logged in.

 

see: '''PUSH'''

 

:* NOTIFY  

:* 290 NOTIFICATION

:: {int4 pending_notifies}|{int4 pending_msgs}  

:* 501 LOGIN FIRST  

:* This command only works if you are logged in.

:* pending_notifies number of animes which have pending notifications for this user.

:* pending_msgs number of unread anidb messages for this user.

:* A client which has registered to recieve UDP notification packets should issue this command once every 30 minutes to keep the connection alive and to ensure that it has not been logged out by the API server yet.

:* If the client did send a NOTIFY within the last 35 minutes and it was confirmed by AniDB then recieving a 501 LOGIN FIRST message for the next NOTIFY command shows that AniDB logged the client out bc it did not respond to a PUSH Notification packet.

:* There is no command to retrieve missed PUSH Notifications.

:* NOTIFYLIST  

:*291 NOTIFYLIST

:: {str type}|{int4 id}

:: {str type}|{int4 id}

:: ...  

:* 501 LOGIN FIRST  

:* This command only works if you are logged in.

:* type is:

:: M for message entries

:: N for notification entries

:*id is the identifier for the notification/message as required by NOTIFYGET.

:* NOTIFYLIST returns one line per entry, if no entries are available only the first line of the reply is returned.

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

:* 292 NOTIFYGET

: [if type = M]

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

: [if type = N]

:: {int4 aid}|{int4 type}|{str count}|{int4 date}|{str anime_name}  

:* 393 NO SUCH ENTRY  

:* 505 ILLEGAL INPUT OR ACCESS DENIED

:* 501 LOGIN FIRST

:* This command only works if you are logged in.

:* type is:

:: M for message entries

:: N for notification entries

:* id is the identifier for the notification/message as required by NOTIFYGET.

:* for message entries (M):

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

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

:* for notification entries (N):

:: aid is the id of the affected anime

:: type is the notification type (0=all, 1=new, 2=group)

:: count is the number of events pending for this anime

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

 

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

:* 282 NOTIFYACK SUCCESSFUL  

:* 382 NO SUCH ENTRY  

:* 505 ILLEGAL INPUT OR ACCESS DENIED  

:* 501 LOGIN FIRST  

:* This command only works if you are logged in.

:* This command will mark a message read or clear a notification.

:* type is:

:: M for message entries

:: N for notification entries

=== SENDMSG: Send Message ===

'''Command String:'''

:* SENDMSG to={str username}&title={str title}&body={str body}  

:* 294 SENDMSG SUCCESSFUL

:* 394 NO SUCH USER

:* 501 LOGIN FIRST

:* This command only works if you are logged in.

:* This command allows you to send an AniDB message.

{{eyecatch|IMPORTANT:|

title must not be longer than 100 chars.

body must not be longer than 1200 chars.

: query by fid:

:* FILE fid={int4 id}  

: query by size+ed2k hash:

:* FILE size={int4 size}&ed2k={str ed2khash}

'''Possible Replies:'''

:* 220 FILE

:: {int4 fid}|{int4 aid}|{int4 eid}|{int4 gid}|{int4 state}|{int4 size}|{str ed2k}|{str anidbfilename}

:* 320 NO SUCH FILE

'''Info:'''

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

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

  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)

  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 ==== 1 ==> FILE_CRCOK ==> file matched official crc and is version 1

  state ==== 8 ==> FILE_ISV3 ==> file was not crc checked and is version 3

:by lid: (mylist id)  

:* MYLIST lid={int4 lid}  

:by fid:  

:* MYLIST fid={int4 fid}  

:by size+ed2k hash:  

:* MYLIST size={int4 size}&ed2k={str ed2khash}  

:* 221 MYLIST

:: {int4 lid}|{int4 fid}|{int4 eid}|{int4 aid}|{int4 gid}|{int4 date}|{int2 state}|{int4 viewdate}|{str storage}|{str source}|{str other}

:* 321 NO SUCH ENTRY

'''Info:'''

=== MYLIST ADD: Add file to mylist ===

:by lid: (mylist id, edit only)  

:* MYLISTADD lid={int4 lid}&edit=1[&state={int2 state}&viewed={boolean viewed}&source={str source}&storage={str storage}&other={str other}]  

:by fid:  

:* MYLISTADD fid={int4 fid}[&state={int2 state}&viewed={boolean viewed}&source={str source}&storage={str storage}&other={str other}][&edit=1]  

:by size+ed2k hash:  

:* MYLISTADD size={int4 size}&ed2k={str ed2khash}[&state={int2 state}&viewed={boolean viewed}&source={str source}&storage={str storage}&other={str other}][&edit=1]  

:* 210 MYLIST ENTRY ADDED  

:* 310 FILE ALREADY IN MYLIST  

:* 311 MYLIST ENTRY EDITED  

:* 410 NO SUCH FILE

:* 411 NO SUCH MYLIST ENTRY  

:* All data except lid/fid/size+hash is optional.

:* Viewed should be 0 for unwatched files and 1 for watched files.

:* Other is the only field which may contrain newlines, but they have to be stored as <br>

:* If edit is 1 then an existing entry, if found, will be updated with the given values.

:* For state values refer to: '''MYLIST'''

:* If you want to change an existing entry and already know it's mylist id (lid) please use the lid-version of this command. It put less load on the server.

=== MYLIST DEL: Remove file from mylist ===

: by lid: (mylist id)

:* MYLISTDEL lid={int4 lid}  

: by fid:

:* MYLISTDEL fid={int4 fid}  

:* 211 ENTRY DELETED

:* 411 NO SUCH ENTRY

:* 505 ILLEGAL INPUT OR ACCESS DENIED

:* Currently this command does not update the internal caches of AniDB. Using this command will lead to wrong stats values/counts being displayed in your Mylist & co @ AniDB for upto 24h.

:* PING

:* 300 PONG

:* May be used by a frontend to determin if the API is sill available.

:* May be executed even if not yet logged in.

At anypoint int the retrieval process you have to expect the following output:  

:* 6xx INTERNAL SERVER ERROR

:: ERROR: {str errormessage}  

:OR  

:*6xx INTERNAL SERVER ERROR - {str errormessage}  

Such errors should be reported back to [[User:Exp|Exp]].

:* 598 UNKNOWN COMMAND