UDP API DEV: Difference between revisions

From AniDB
Jump to navigation Jump to search
mNo edit summary
(cleaned)
Line 7: Line 7:
== Data Commands ==
== Data Commands ==
=== [[UDP_API_Definition#ANIME:_Retrieve_Anime_Data|ANIME]] ===
=== [[UDP_API_Definition#ANIME:_Retrieve_Anime_Data|ANIME]] ===
'''Command String:'''<br>
by aid
* ANIME aid={int4 id}'''[&acode={int4}]'''
by name
* ANIME aname={str anime name}'''[&acode={int4}]'''
'''acode:'''
{| cellpadding="0" align="center"
! width="40"|Bit
! width="80"|Decimal
! width="160"|Data field
! width="50"|-
! width="40"|Bit
! width="120"|Decimal
! width="160"|Data field
|- style="background-color: #eee;"
|0 ||1 || int4 aid || || 16 || 65536 || str url
|-
|1 ||2 || int4 episodes || || 17 || 131072 || str picname
|- style="background-color: #eee;"
|2 ||4 || int4 normal ep count || || 18 || 262144 || str year
|-
|3 ||8 || int4 special ep count ||  || 19 || 524288 || str type
|- style="background-color: #eee;"
|4 ||16 || int4 rating || || 20 || 1048576 || str romaji name
|-
|5 ||32 || int4 vote count || || 21 || 2097152 || str kanji name
|- style="background-color: #eee;"
|6 ||64 || int4 temp rating || || 22 || 4194304 || str english name
|-
|7 ||128 || int4 temp vote count || || 23 || 8388608 || str other name
|- style="background-color: #eee;"
|8 ||256 || int4 average review rating || || 24 || 16777216 || str short name list
|-
|9 ||512 || int4 review count || || 25 || 33554432 || str synonym list
|- style="background-color: #eee;"
|10 ||1024 || int4 air date || || 26 || 67108864 || str category list
|-
|11 ||2048 || int4 end date || || 27 || 134217728 || str related aid list
|- style="background-color: #eee;"
|12 ||4096 || int4 anime planet id || || 28 || 268435456 || str producer name list
|-
|13 ||8192 || int4 anime news network id || || 29 || 536870912 || str producer id list
|- style="background-color: #eee;"
|14 ||16384 || int4 allcinema id || || 30 || 1073741824 || str award list
|-
|15 ||32768 || str animenfo id || || 31 || -2147483648 || reserved (all)
|}
=== [[UDP_API_Definition#ANIMEINFO:_Retrieve_Anime_Data|ANIMEINFO]] ===
'''Syntax:'''
* ANIMEINFO aid={int4 id} | aname={str animename}
'''Replies:'''
* This command should return all missing informations from ANIME, sush as companies, external links (ANN, ...), awards, ...--[[User:Darsh|Darsh]] 12:10, 19 April 2006 (CEST)
: OK. But included in ANIME with an argument, like acode.--[[User:Epoximator|Epoximator]] 00:18, 21 April 2006 (CEST)
:: Thanks, but what about awards? Moreover I'm not sure that having few commands that returns a lot of data is the best solution. --[[User:Darsh|Darsh]] 22:50, 01 May 2006 (CEST)
::: Added awards. Not sure what you mean... You only request what you need by setting the corresponding bits in acode. --[[User:Epoximator|Epoximator]] 11:02, 2 May 2006 (CEST)
:::: I'm not sure of this, since I don't know how the server is implemented and how the database schema is, but doing so require a lot of work by the server. Moreover the available bits are only 32... --[[User:Darsh|Darsh]] 19:07, 01 May 2006 (CEST)


=== [[UDP_API_Definition#EPISODE:_Retrieve_Episode_Data|EPISODE]] ===
=== [[UDP_API_Definition#EPISODE:_Retrieve_Episode_Data|EPISODE]] ===
Line 72: Line 13:


=== [[UDP_API_Definition#FILE:_Retrieve_File_Data|FILE]] ===
=== [[UDP_API_Definition#FILE:_Retrieve_File_Data|FILE]] ===
'''Possible return codes:'''
* 322 MULTIPLE FILES FOUND
: {int4 fid 0}|{int4 fid 1}|...|{int4 fid n}
'''Comments:'''<br>
Selection by anime, group and episode number is not unique. As an example: FILE aid=22&gid=41&tag=tag0002&epno=1 <br>
This commands always return only the first match. --[[User:Darsh|Darsh]] 12:10, 19 April 2006 (CEST)
: Can be fixed with MULTIPLE FILES FOUND, or just return the latest version. Maybe selectable with an argument.--[[User:Epoximator|Epoximator]] 00:18, 21 April 2006 (CEST)
Add {str anidbfilename} to fcode?  --[[User:Darsh|Darsh]] 10:56, 25 April 2006 (CEST)
: ok. bit 30 @ fcode --[[User:Epoximator|Epoximator]] 21:34, 28 April 2006 (CEST)
=== PRODUCER ===
'''Command String:'''<br>
by id
* PRODUCER pid={int4 producer id}
by name
* PRODUCER pname={str producer name/short name/other name}
'''Possible Replies:'''
* 245 PRODUCER
: {int4 id}|{str name}|{str short name}|{str other name}|{str type}|{str picture name}|{str home page url}
* 345 NO SUCH PRODUCER
'''Example:'''
  > PRODUCER pid=1
  < 245 PRODUCER
  1|GAINAX||ガイナックス|Company|1088.gif|http://www.gainax.co.jp/
== Buddy Commands ==
Group of commands used to administrate your buddylist.
=== BUDDYADD ===
'''Command String:'''
* BUDDYADD uid={int4 buddy uid}
* BUDDYADD uname={int4 buddy name}
'''Possible Replies:'''
* 394 NO SUCH USER
* 255 BUDDY ADDED
* 355 BUDDY ALREADY ADDED
=== BUDDYDEL ===
'''Command String:'''
* BUDDYDEL uid={int4 buddy uid}
'''Possible Replies:'''
* 356 NO SUCH BUDDY
* 256 BUDDY DELETED
=== BUDDYACCEPT ===
'''Command String:'''
* BUDDYACCEPT uid={int4 user uid}
'''Possible Replies:'''
* 356 NO SUCH BUDDY
* 257 BUDDY ACCEPTED
* 357 BUDDY ALREADY ACCEPTED
=== BUDDYDENY ===
'''Command String:'''
* BUDDYDENY uid={int4 buddy uid}
'''Possible Replies:'''
* 394 NO SUCH USER
* 258 BUDDY DENIED
* 358 BUDDY ALREADY DENIED
=== BUDDYLIST ===
'''Command String:'''
* BUDDYLIST startat={int2 start at #}
'''Possible Replies:'''
* 253 {int2 start} {int2 end} {int2 total} BUDDY LIST
: {int4 uid}|{str username}|{int2 state}
: ...
'''Info:'''
* state is a 16bit bit field in integer notation (lowest bit first):
  * bit 1 = this user is in your buddylist
  * bit 2 = this user has accepted you
  * bit 3 = this user is waiting for your approval
=== BUDDYSTATE ===
'''Command String:'''
* BUDDYSTATE startat={int2 start at #}
'''Possible Replies:'''
* 254 {int2 start} {int2 end} {int2 total} BUDDY STATE
: {int4 uid}|{int2 onlinestate}
: ...
'''Info:'''
* 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)
  * bit 2 = udp api online (user is currently connected to the udp api server)
  * example: 0=offline, 1=http online, 2=udp api online, 3=http&udp api online
=== [[UDP_API_Definition#NOTIFY:_Notifications|NOTIFY]] : extend ===
'''Command String:'''
* NOTIFY '''[buddy=1]'''
'''Notification Packet Format:'''
* Extension of notification:
  290 NOTIFICATION
  {int4 pending_notifies}|{int4 pending_msgs}|{int4 number_of_online_buddys}
That way if we requested a notify command and number_of_online_buddys was more than 0 we could then do a BUDDYLIST to get the status of the users.
=== [[UDP_API_Definition#PUSH:_UDP_Notification_Registration|PUSH]] : extend ===
'''Command String:'''
* PUSH notify={bool push_file_added_notifications}&msg={bool push_msg_added_notifications}'''[&buddy={bool push_buddy_event_notifications}]'''
'''Notification Packet Format:'''
* Buddy Event Notify:
  273 {int4 notify_packet_id} NOTIFICATION
  {int4 buddy uid}|{int2 event type}
:* Possible event types:
  0 => LOGIN
  1 => LOGOUT
  2 => ACCEPTED
  3 => ADD (?)


== Misc Commands ==
== Misc Commands ==
=== ENCRYPT ===
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.
'''Command String:'''
* ENCRYPT user={str name}[&type={int2 type}]
'''Possible Replies:'''
* 209 {str salt} ENCRYPTION ENABLED
* 309 API PASSWORD NOT DEFINED
* 509 NO SUCH ENCRYPTION TYPE
* 394 NO SUCH USER
'''Info:'''
* ''user'' is the user name.
* ''type'' is the type of encryption; 1 => 128 bit AES (only one defined).
* ''API Password'' is the one defined in the profile settings [http://anidb.info/perl-bin/animedb.pl?show=profile page].
* 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.
* In order to minimize server load, encryption should be disabled by default and should have to be enabled manually by the user in the configuration options.
* The encryption key is md5(api_password_of_user+''salt'').
=== ENCODING ===
Sets preferred [http://en.wikipedia.org/wiki/Character_encoding encoding] per session.
'''Command String:'''
* ENCODING name={str encoding name}
'''Possible Replies:'''
* 219 ENCODING CHANGED
* 519 ENCODING NOT SUPPORTED
'''Info:'''
* Supported encodings: http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html
* Default: ASCII.
* Resets to default on logout.
=== [[UDP_API_Definition#AUTH:_Authing_to_the_AnimeDB|AUTH]] : extend ===
'''Command String:'''
* 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}''']
'''Info:'''
* 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 not supported then the argument will be silently ignored. Use ENCODING to test what works.
**Supported encodings are [http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html these].
* ''comp=1'' means that the client supports compression ([http://java.sun.com/j2se/1.5.0/docs/api/java/util/zip/Deflater.html DEFLATE]).
**The server will compress (instead of truncating) the datagrams when needed if this option is enabled.
**The first two bytes of compressed datagrams will always be set to zero. (So tags should never start with that.)
* Default [http://en.wikipedia.org/wiki/MTU_(networking) ''mtu''] is 1400. Min = 400, Max = 1400.
=== USER: Retrieve user uid ===
'''Command String:'''
* USER user={str user name}
'''Possible Replies:'''
* 394 NO SUCH USER
* 295 USER
: {int4 uid}
'''Info:'''
* The client should the check length (3-10) and case (lower) of ''user'' before sending.
== API Status Notification ==
=== GOINGDOWN ===
Clients with any notification on will receive the GOINGDOWN message before the API goes offline.
'''Notification Packet Format:'''
  XXX {int4 notify_packet_id} NOTIFICATION
  {int4 time offline}|{int4 comment}
'''Info:'''
* 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.
* Only one datagram will be sent, and the server will not listen for replies.
'''Comment:'''
: Time offline and comment will most likely not be specified normally. '0|None' will be the default and should indicate restart for update. --[[User:Epoximator|Epoximator]] 20:52, 28 April 2006 (CEST)


== USER LIST COMMANDS ==
== USER LIST COMMANDS ==

Revision as of 10:08, 23 July 2006

UDP API DEVELOPMENT

  • add feature requests here
  • feel free to edit / comment / whatever

Data Commands

ANIME

EPISODE

GROUP

FILE

Misc Commands

USER LIST COMMANDS

USERLIST : Retrieve Mylist Data of a specified user

Feature Request  : The purpose is for a client I want to make, which will essentially be a more user friendly method of viewing and manipulating the view of a user's list. Sort by various categories and so on. I would like to be able to view and browse a specified user's list just as I can with the web interface

Probably best implemented to behave just like the mylist commands.

Command String:
by lid: (userlist user={str name}&id)

  • USERLIST user={str name}&lid={int4 lid}

by fid:

  • USERLIST user={str name}&fid={int4 fid}

by size+ed2k hash:

  • USERLIST user={str name}&size={int4 size}&ed2k={str ed2khash}

by anime + group + epno

  • USERLIST user={str name}&aname={str anime name}&gname={str group name}&epno={int4 episode number}
  • USERLIST user={str name}&aname={str anime name}&gid={int4 group id}&epno={int4 episode number}
  • USERLIST user={str name}&aid={int4 anime id}&gname={str group name}&epno={int4 episode number}
  • USERLIST user={str name}&aid={int4 anime id}&gid={int4 group id}&epno={int4 episode number}

Possible Replies:

  • 221 USERLIST
{int4 lid}|{int4 fid}|{int4 eid}|{int4 aid}|{int4 gid}|{int4 date}|{int2 state}|{int4 viewdate}|{str storage}|{str source}|{str other}
  • 322 MULTIPLE FILES FOUND
{str anime title}|{int episodes}|{str eps with state unknown}|{str eps with state on hhd}|{str eps with state on cd}|{str eps with state deleted}|{str watched eps}|{str group 1 short name}|{str eps for group 1}|...|{str group N short name}|{str eps for group N}
  • 321 NO SUCH ENTRY

Info:

  • The state field provides information about the location and sharing state of a file in mylist.
  • If files are added after hashing, a client should specify the state as 1 (on hdd) (if the user doesn't explicitly select something else).
  • eps is a list of episodes, e.g. "1-12,14-16,T1"

States:

 0 - unknown - state is unknown or the user doesn't want to provide this information
 1 - on hdd - the file is stored on hdd (but is not shared)
 2 - on cd - the file is stored on cd
 3 - deleted - the file has been deleted or is not available for other reasons (i.e. reencoded)

Example:

 > USERLIST user=baka&aname=gits sac&s=xxxxx
 < 322 MULTIPLE FILES FOUND
 Koukaku Kidoutai STAND ALONE COMPLEX|26||1-26|1-26,S2-S27|||V-A|S2-S27|LMF|20-26|KAA|1-26|AonE|1-19|Anime-MX|1-3,9-20

Comments:
It would probably be ok to add this, but note that it would be a hassle to fetch a complete mylist. I mean, you can already do this with your own list, but it takes a lot of time because of the datagram rate limit. (It would take at least 8h to fetch my own list). And that is usage we don't really want @ udp api. And a command that returns all the data at once will, of course, not be allowed. So, in other words, if you just want to check if a friend has a specific file, or what files per anime (multiple files found), then ok, but view and browse a specified user's list just as I can with the web interface is not likely to happen/be allowed.--Epoximator 11:29, 4 June 2006 (CEST)

What I'm really interested in is maintaining local dbs of 3/4 user lists and having a client automatically update them every 2/3 weeks. We use this to coordinate information within our country regarding who has what =p. But what we're interested in is a way to be able to selectively retrieve the entire list by some index. OFcourse if its slow, then it makes sense to maintain it locally and just look for changes. The other thing I really want is to somehow retrieve with mylist file data (or user list file data), the date at which something was added to the list. (I understand this information exists). The idea here is we can locally query these lists for files added within the last 2/3 months. --path 11:53, 25 June 2006 (IST)
That's really not wanted usage for this api. Have you thought about the possibility to use mylist export? You know you can make you own export template and get all the info you want at once? A command that query all changes (lids) within the last 2/3 months (or even weeks) is not going to be added. --Epoximator 12:36, 25 June 2006 (UTC)