API Design Questions (4)

[Gervase Markham]

On 23/09/09 12:14, Gervase Markham wrote:
> Here are some things I've run into when designing the RESTful API.
> Perhaps people could tell me what they think the best option is.

Lots more today :-)

* When returning an array as the value of a hash, is the key singular or 
plural? Remember, the array could have one member.

{ "bugs? or bug?":
   [
     { "id": 1, "comment?": [ { ... }, { ... }, ... ], ... },
     { "id": 2, ... },
     { "id": 3, ... }
   ]
}

* 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?

* Various REST evangelists say that APIs are only properly restful if 
all links between objects use their API URLs. That would suggest that we 
want e.g.:

{
   blocks: [ "http://bzapi.example.com/bug/23",
             "http://bzapi.example.com/bug/76" ]
}

rather than

{
   blocks: [ 23, 76 ]
}

Would the former be overdoing it?

* Similarly, I am currently "upgrading" all user references 
(assigned_to, reporter, attacher, setter etc.) to User objects, which 
contain a "name" (email address or short form), "ref" for the full user 
object and (on the /user interface) a real_name:

"assigned_to": {
   "name": "gerv at mozilla.org",
   "ref": "http://localhost:3000/user/gerv@mozilla.org"
}

Is this also overdoing it?

* The XML-RPC API tidies up quite a few field names, which is great. 
Here are some more candidates - what do you think?

- cclist_accessible => cc_accessible
   (to match 'reporter' => 'reporter_accessible' and 'cc')
- dependson => depends_on (we are adding underscores, it seems)
- everconfirmed => ever_confirmed (of course, this is read only)


* (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?

* There's no longer a qacontact_accessible, right?

Gerv
_______________________________________________
dev-apps-bugzilla mailing list
dev-apps-bugzilla at lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-apps-bugzilla