API Design Questions (4)

[Max Kanat-Alexander]

On 09/29/2009 04:56 AM, Gervase Markham wrote:
> * When returning an array as the value of a hash, is the key singular or
> plural? Remember, the array could have one member.

	I'd stick as close as possible to the current XML-RPC return values as
possible. So it's "bugs".

> * Time formats. The XML-RPC API returns e.g. 20090923T11:02:34. Other
> APIs return "2009-09-23 11:02:34". Both are valid ISO 8601 (the former
> is basic, the latter extended). Should we go with the latter as more
> human-readable?

	The most important thing is that you return time zones. The current
JSON-RPC API is going to be modified to return some other time format
than it currently returns in HEAD, although at the moment I'm actually
forgetting what the format will be--it's something that the YUI JSON
stuff understands and uses correctly, though....

> Would the former be overdoing it?

	I think so.

> Is this also overdoing it?

	I think so. For parsing, it's probably just easiest to include just the
username. But maybe it'd be better to always include a full user object
with username and fullname, because otherwise people will have to make
one call per user to get their full name. (With XML-RPC it's easy to
specify lots of users in one call, so this isn't a problem, but with
REST I'm not sure it's as easy, and there's a limit on URL lengths.)

> - cclist_accessible => cc_accessible
>   (to match 'reporter' => 'reporter_accessible' and 'cc')

	Sounds good.

> - dependson => depends_on (we are adding underscores, it seems)

	Sounds good.

> - everconfirmed => ever_confirmed (of course, this is read only)

	Sure.

> * (It's OK if no-one knows this.) We don't provide product IDs or
> component IDs on the legacy XML interface. Why do we provide
> classification IDs? Should I remove them from the returned data?

	I think we provide all those IDs in config.cgi--I have no idea why we'd
provide them in bug XML, though....

> * There's no longer a qacontact_accessible, right?

	Right.

	-Max
-- 
http://www.everythingsolved.com/
Competent, Friendly Bugzilla and Perl Services. Everything Else, too.