UDP API DEV

UDP API DEVELOPMENT

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

Data Commands

ANIME

Command String:
by aid

• ANIME aid={int4 id}[&acode={int4}]

by name

• ANIME aname={str anime name}[&acode={int4}]

acode:

Bit	Decimal	Data field	-	Bit	Decimal	Data field
0	1	int4 aid		16	65536	str url
1	2	int4 episodes		17	131072	str picname
2	4	int4 normal ep count		18	262144	str year
3	8	int4 special ep count		19	524288	str type
4	16	int4 rating		20	1048576	str romaji name
5	32	int4 vote count		21	2097152	str kanji name
6	64	int4 temp rating		22	4194304	str english name
7	128	int4 temp vote count		23	8388608	str other name
8	256	int4 average review rating		24	16777216	str short name list
9	512	int4 review count		25	33554432	str synonym list
10	1024	int4 air date		26	67108864	str category list
11	2048	int4 end date		27	134217728	str related aid list
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
14	16384	int4 allcinema id		30	1073741824	str award list
15	32768	str animenfo id		31	-2147483648	reserved (all)

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, ...--Darsh 12:10, 19 April 2006 (CEST)

OK. But included in ANIME with an argument, like acode.--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. --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. --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... --Darsh 19:07, 01 May 2006 (CEST)

FILE

Possible return codes:

• 322 MULTIPLE FILES FOUND

{int4 fid 0}|{int4 fid 1}|...|{int4 fid n}

Comments:
Selection by anime, group and episode number is not unique. As an example: FILE aid=22&gid=41&tag=tag0002&epno=1
This commands always return only the first match. --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.--Epoximator 00:18, 21 April 2006 (CEST)

Add {str anidbfilename} to fcode? --Darsh 10:56, 25 April 2006 (CEST)

ok. bit 30 @ fcode --Epoximator 21:34, 28 April 2006 (CEST)

PRODUCER

Command String:
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

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.

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

ENCRYPT

Will cause all future messages from the server, except the first (the reply to the ENCRYPT command itself), to be encrypted (128 bit 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 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 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 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.

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 these.
• comp=1 means that the client supports compression (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 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. --Epoximator 20:52, 28 April 2006 (CEST)

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)

---