Including and excluding fields

[Gervase Markham]

I would like to implement a system in the BzAPI for people to be able to
control what fields they get back on objects.

Here are some design goals:

1) Generic - works for all object types
2) Robust in the face of future new fields
3) Makes it so the default (no field specifications) is useful

Here are my use cases:

A) "Give me everything"
B) "Give me just these <small number of> named fields"
C) "Give me as much as possible while still being fast"

Goal 3) makes me think that each call (e.g. the /bug/<id> single bug
call or the /bug?foo=bar search) would have a set of default fields,
which will not be every possible field. That is true today - by default,
the single bug call doesn't return comments, attachmentdata or history,
and the search call only returns a subset of fields (basically, the
single-valued ones, with the exception of URL[0]). It seems that goal 3)
and use case C) fit rather well. The default should be "what's fast" -
so, for a search, everything in the bugs table, and for a single bug,
everything that doesn't have an unbounded size (and so the download time
can be O(N)).

Use case B) suggests we need a "fields=" parameter which specifies the
fields you want. That's fine for goal 1) and goal 2) - adding new fields
doesn't affect this.

So how do we hit use case A)? If the default is not everything, and you
have a "fields" parameter which starts from scratch, you have to know
the name of every field, or if it starts from the default, you have to
know the name of every non_default field. Which isn't great if someone
e.g. adds a new custom field. So we need a special value - "all" - for
"fields", and then an exclude_fields option to subtract from that if
people want to avoid getting big or slow fields.

So my design is:

fields=<comma-separated list of field names, or "all", starting from
        the default and adding>
exclude_fields=<comma-separated list of field names to not send>

"exclude_fields" overrides "fields".

A field name can be a compound field name, e.g. attachments.data, which
is the 'data' member of everything in the 'attachments' array.

Algorithm: find data for all default fields, plus all fields in
"fields". Throw away data for all fields in "exclude_fields".

Note that this is different from the current design for the XML-RPC API,
which as an include_fields parameter which, if used, starts from scratch
rather than from the default, and doesn't have an "all" parameter. To my
mind, that doesn't meet goal 2). But I've made the name of my field
adding parameter different to avoid confusion.

What's wrong with my design? :-)

Gerv

[0] https://bugzilla.mozilla.org/show_bug.cgi?id=25275
_______________________________________________
dev-apps-bugzilla mailing list
dev-apps-bugzilla at lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-apps-bugzilla