API Design Questions

[Gervase Markham]

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.

Attachments
-----------

The current design uses URLs of the form:
/bug/<bugid>/attachment/<attachid>

However, attachids are globally unique, not per-bug unique. And this URL
form means you need to know the bug number before you can access the
attachment, which seems unnecessary (or it would mean the API just
ignored the bug number, which seems somewhat dumb too). If all you have
is e.g. a standard attachment URL, you don't have the bug number.

So should I change it to use URLs simply of the form
/attachment/<attachid>

?

Comments
--------

A similar question arises with comments, where the comment IDs used on
the interface are globally unique. Do you think people would prefer to
access individual comments using URIs like:
/bug/<bugid>/comment/0
/bug/<bugid>/comment/3
(i.e. indexed by count in the bug, as you might get from
"show_bug.cgi?id=123456#45")

or like

/comment/13535
/comment/43487

? I think the former (i.e. different from the attachments case), but I'd
be interested in the opinions of others. But if we do use the former,
what do we do with the globally-unique comment IDs? Suppress them
because they'd cause confusion?

Gerv



_______________________________________________
dev-apps-bugzilla mailing list
dev-apps-bugzilla@...
https://lists.mozilla.org/listinfo/dev-apps-bugzilla
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[Frédéric Buclin]

Le 23. 09. 09 13:14, Gervase Markham a écrit :
> So should I change it to use URLs simply of the form
> /attachment/<attachid>

That's what we currently use when accessing attachments from a web
browser. We don't need the bug ID.


> /bug/<bugid>/comment/0

This makes more sense to me.


LpSolit
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[j r-15]

I like this method

/comment/13535
/comment/43487

of each bug it can referance all of the comments and the comments can back reference the bug. These ID's are independant from the bug ID. This method opens up the possibility of having a comment as part of multiple bugs. This could be a good or bad thing.

J Richmond

[Gervase Markham]

On 23/09/09 15:28, j r wrote:
> I like this method
>>
>> /comment/13535
>> /comment/43487
>>
>
> of each bug it can referance all of the comments and the comments can back
> reference the bug.

That will happen anyway. :-)

> These ID's are independant from the bug ID. This method
> opens up the possibility of having a comment as part of multiple bugs. This
> could be a good or bad thing.

I don't think that's a particularly good thing. And anyway, the other
scheme has that possibility; the above one would just let you tell when
two comments are, in fact, the same comment. Which doesn't sound all
that useful.

Gerv
_______________________________________________
dev-apps-bugzilla mailing list
dev-apps-bugzilla@...
https://lists.mozilla.org/listinfo/dev-apps-bugzilla
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[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.

And another one :-)

We update bugs with a PUT of a JSON representation:

{
   bug: { priority: P1, assigned_to: { name: gerv@...,
real_name: "Gervase Markham" }, ... }
}

(At the moment, users are always represented by "user objects" - hashes
in the JSON interface - which can have a number of keys and values. This
makes the API more understandable; it would be odd if assigned_to was a
hash for data coming out, but a scalar for data going in. But obviously,
when PUTting a new value, we only look at the "name" key.)

What is the best way of issuing meta-instructions, like "set assigned_to
to default"?

Do you:

1) Not provide that feature?

2) have a magic value for the "assigned_to" in the bug hash:

{
   bug: { priority: P1, assigned_to: { default: 1 }, ... }
}

3) Support an extra bug hash key "set_default_assignee:

{
   bug: { priority: P1, set_default_assignee: 1, ... }
}

4) Have an additional "instructions" hash:

{
   bug: { priority: P1, ... }
   instructions: { set_default_assignee: 1 }
}

5) Something else?

Gerv
_______________________________________________
dev-apps-bugzilla mailing list
dev-apps-bugzilla@...
https://lists.mozilla.org/listinfo/dev-apps-bugzilla
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[Max Kanat-Alexander]

On 09/23/2009 04:14 AM, Gervase Markham wrote:
> So should I change it to use URLs simply of the form
> /attachment/<attachid>

        Yeah, probably.

> [snip]
> or like
>
> /comment/13535
> /comment/43487

        Probably both, but I definitely plan to start using comment ids in as
many places in the future instead of comment numbers. Also,
theoretically comment numbers can change, but comment ids can't.

        -Max
--
http://www.everythingsolved.com/
Competent, Friendly Bugzilla and Perl Services. Everything Else, too.
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[Max Kanat-Alexander]

On 09/23/2009 10:03 AM, Gervase Markham wrote:
> What is the best way of issuing meta-instructions, like "set assigned_to
> to default"?

        Just don't specify assigned_to.

        -Max
--
http://www.everythingsolved.com/
Competent, Friendly Bugzilla and Perl Services. Everything Else, too.
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[Max Kanat-Alexander]

On 09/23/2009 02:57 PM, Max Kanat-Alexander wrote:
>> /comment/13535
>> /comment/43487
>
> Probably both, but I definitely plan to start using comment ids in as
> many places in the future instead of comment numbers. Also,
> theoretically comment numbers can change, but comment ids can't.

        However, I'd also ask why you'd ever need to have a URL for just one
comment.

        -Max
--
http://www.everythingsolved.com/
Competent, Friendly Bugzilla and Perl Services. Everything Else, too.
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[Gervase Markham]

On 23/09/09 22:59, Max Kanat-Alexander wrote:
> Just don't specify assigned_to.

Hmm. I guess for simplicity of API use I wanted people to be able to
send stuff like:

{ "priority": "P5" }

and have that do the obvious, simple thing. But if absence of a field
means something, then that breaks. This would mean you'd always have to
GET every bug before PUTting it, even if you had most of a
representation of that bug from the call which lists bugs.

But then, maybe the RESTful way is that you have to PUT an entire
representation? But you might say that you are doing that in the case
above, you are just saying "everything else is assumed not to change"...

Gerv

_______________________________________________
dev-apps-bugzilla mailing list
dev-apps-bugzilla@...
https://lists.mozilla.org/listinfo/dev-apps-bugzilla
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[Gervase Markham]

On 23/09/09 22:57, Max Kanat-Alexander wrote:
> On 09/23/2009 04:14 AM, Gervase Markham wrote:
>> So should I change it to use URLs simply of the form
>> /attachment/<attachid>
>
> Yeah, probably.

OK.

>> /comment/13535
>> /comment/43487
>
> Probably both, but I definitely plan to start using comment ids in as
> many places in the future instead of comment numbers. Also,
> theoretically comment numbers can change, but comment ids can't.

"Theoretically" meaning that in the future we may introduce a feature
which inserts comments into the middle of the stream, but we haven't
yet? Or meaning that Bugzilla already does this in some circumstances?

I know we don't renumber when some comments are made private. And if we
did do this, people's URLs would break...

Gerv
_______________________________________________
dev-apps-bugzilla mailing list
dev-apps-bugzilla@...
https://lists.mozilla.org/listinfo/dev-apps-bugzilla
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[Gervase Markham]

On 23/09/09 23:00, Max Kanat-Alexander wrote:
> However, I'd also ask why you'd ever need to have a URL for just one
> comment.

Good question, I guess. Maybe I was going overboard on the REST "every
object must be identified and have a URL reference" thing.

Gerv
_______________________________________________
dev-apps-bugzilla mailing list
dev-apps-bugzilla@...
https://lists.mozilla.org/listinfo/dev-apps-bugzilla
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[Max Kanat-Alexander]

On 09/24/2009 03:14 AM, Gervase Markham wrote:
> and have that do the obvious, simple thing. But if absence of a field
> means something, then that breaks. This would mean you'd always have to
> GET every bug before PUTting it, even if you had most of a
> representation of that bug from the call which lists bugs.

        Oh, you mean that you want some way to reset things to the default when
updating bugs! Just set them null as opposed to an empty string.

        -Max
--
http://www.everythingsolved.com/
Competent, Friendly Bugzilla and Perl Services. Everything Else, too.
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[Gervase Markham]

On 24/09/09 11:31, Max Kanat-Alexander wrote:
> Oh, you mean that you want some way to reset things to the default when
> updating bugs! Just set them null as opposed to an empty string.

So you are saying, for qa_contact:

missing      => no change
null         => reset to default
empty string => no QA contact
user object  => that user

? I guess that's unambiguous. Is it also intuitive? :-)

Gerv

_______________________________________________
dev-apps-bugzilla mailing list
dev-apps-bugzilla@...
https://lists.mozilla.org/listinfo/dev-apps-bugzilla
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[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.

Question 3:

Fields in Bugzilla bugs have varying levels of optionalness, from custom
fields, which of course are never guaranteed to be present because they
are product-specific, via those fields such as qa_contact which can be
disabled in the Admin, through to assigned_to or status, which must
always be present and set.

Question: when returning a representation of a bug, what do we do for
fields which do not have a value set? Examples include an empty list of
CCs or See Alsos, or resolution for open bugs, or a blank status whiteboard.

You could either:

A) omit them from the hash
B) provide them, but with a "" or [] value

B) has the advantage that people processing the JSON don't have to
handle the non-existence case with an extra "if" test or "defined" test
for each field. However, obviously, custom fields have to be in class A.
And you could argue there's a simplicity to just putting everything in
class A.

Do we do A) for everything, or do we try and divide the fields Bugzilla
supports into "always supported" and "sometimes supported" and deal with
the always ones (e.g. resolution, keywords) using method B)?

Gerv
_______________________________________________
dev-apps-bugzilla mailing list
dev-apps-bugzilla@...
https://lists.mozilla.org/listinfo/dev-apps-bugzilla
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[Max Kanat-Alexander]

On 09/24/2009 03:37 AM, Gervase Markham wrote:
> ? I guess that's unambiguous. Is it also intuitive? :-)

        I think so--an empty string is a literal "empty", where a null is
instead a special "empty". And if it's not intuitive for some people, it
can be documented somewhere.

        -Max
--
http://www.everythingsolved.com/
Competent, Friendly Bugzilla and Perl Services. Everything Else, too.
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[Max Kanat-Alexander]

On 09/24/2009 03:44 AM, Gervase Markham wrote:
> Fields in Bugzilla bugs have varying levels of optionalness, from custom
> fields, which of course are never guaranteed to be present because they
> are product-specific,

        No, actually, custom fields are always present. The product-specific
bit (which exists only in 3.4) is all done via JS in the UI.

> B) provide them, but with a "" or [] value

        I'm in favor of this since it makes it easier for clients.

        In fact, I'm in favor of returning fields even if they're disabled
(like status_whiteboard when the usestatuswhiteboard parameter is turned
off), unless they are marked as obsolete in the fielddefs table (for
example, you wouldn't return qacontact_accessible). It's best if
parameters just control the UI, and the underlying structure is always
the same.

        -Max
--
http://www.everythingsolved.com/
Competent, Friendly Bugzilla and Perl Services. Everything Else, too.
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[Gervase Markham]

On 24/09/09 11:55, Max Kanat-Alexander wrote:
> On 09/24/2009 03:44 AM, Gervase Markham wrote:
>> Fields in Bugzilla bugs have varying levels of optionalness, from custom
>> fields, which of course are never guaranteed to be present because they
>> are product-specific,
>
> No, actually, custom fields are always present. The product-specific
> bit (which exists only in 3.4) is all done via JS in the UI.

So what happens if someone tries to set a custom field on a bug which is
in a product which it's not enabled for, a) via the UI and b) via the
Web Services interface?

>> B) provide them, but with a "" or [] value
>
> I'm in favor of this since it makes it easier for clients.

This is hard to implement right now for custom fields, because the
legacy XML interface, which I am using under the covers because it
returns more data than the XML-RPC one, doesn't return them unless they
are set. We could fix that, of course.

But in general, I will try and go with principle B.

Gerv

_______________________________________________
dev-apps-bugzilla mailing list
dev-apps-bugzilla@...
https://lists.mozilla.org/listinfo/dev-apps-bugzilla
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[Max Kanat-Alexander]

On 09/24/2009 04:01 AM, Gervase Markham wrote:
> So what happens if someone tries to set a custom field on a bug which is
> in a product which it's not enabled for, a) via the UI and b) via the
> Web Services interface?

        It gets set.

> This is hard to implement right now for custom fields, because the
> legacy XML interface, which I am using under the covers because it
> returns more data than the XML-RPC one, doesn't return them unless they
> are set. We could fix that, of course.

        That may be an artifact of the custom code being used on
bugzilla.mozilla.org, and not the result of our actual custom field code.

        -Max
--
http://www.everythingsolved.com/
Competent, Friendly Bugzilla and Perl Services. Everything Else, too.
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[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@...",
   "ref": "http://localhost:3000/user/gerv@..."
}

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@...
https://lists.mozilla.org/listinfo/dev-apps-bugzilla
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>

[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.
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists@...>