Summary: The API does not adequately deal with "categories" of data,
e.g. "Personal", "Home", "Custom Category". In this regard, the API's
data model is not compatible with the observed behavior of the Gmail
I'm referring here to the categories of data as shown on the Gmail
"edit contact" page, and comparing it tothe resulting XML from the
API. I'm using phoneNumber to show these issues, but similar
ambiguities extend to other elements.
First issue: Duplicate category names. Gmail allows these. I can have
two categories named exactly the same, e.g. "Work". onsider the next
two sibling elements from the same XML response:
In reality, they belong to entirely different logical groupings on my
Gmail page, but from the API there is no distinction, no way to guess
which is which. I have no idea what would happen if I changed one.
Would it overwrite two different e-mail addresses? Which e-mail is
grouped with (not shown) a "Work" cell-phone number?
Second issue: The methods for accessing category names are somewhat
inconsistent and arbitrary.
Consider the following XML snippet, with phone number "subtypes" like
So sometimes you need to check "rel" for the category, sometimes for
the category, except when there is a sub-type, then you check "label".
Except when it's a fax, ad you have to check "rel" again!
Third issue (building on #2): Some categories are treated specially
and add to the mish-mash. Any category (apparently based solely on the
given name) of "Work" or "Personal" or "Other" is treated differently
from "My Category". This next block shows the given Gmail category
name (case sensitive) in a quote, followed by the generated XML
element. All of these elements could be in the same entry at once.
When "rel=*#other", it means the category "Other" or the no-category
The category "other" in lowercase however means we look at the label
The category "Personal" maps to looking for rel=$#home
But the category "Home" or "home" actually means we look inside the
The category "Other" means looking inside the rel= attribute
The category "other" mans looking inside the label...
"Okay, smartypants, how would you do it?"
I really can't speak for the backwards compatibility issues, but I
think we need to scrap this "category" label business in favor of a
way to get category IDs. Then toss on a "category_id" attribute and
use that to refer to a set of <contactCategory> elements.
That is, unless the backend is fixed to not allow duplicates so that
the name of the category can be used directly, in which case it's a
matter of category= and subtype= attributes.
Hello, Currently GMail has two UIs for the Contacts interface, an older one and a newer one (you can switch between them on the upper-right hand corner of GMail). The new interface does not provide an interface to specify custom categories, nor does it indicate a logical grouping between different fields in the same category. This is the interface that the API is emulating.
However, since this information is available internally, I've filed a ticket to have this functionality added to the API:
Unfortunately, you still do need to check rel and label, since either one could contain data, but neither will be specified at the same time. We use rel whenever possible since this is more precise, but since custom category names aren't specified in our schema we're forced to use label for everything else. This is also why some categories are treated specially.
As for the changes in what's treated specially, there's inevitably some tweaking in a new API as we fix bugs and get behavior right. However, since our goal is to provide a stabile foundation to build applications, we try to keep these changes to a minimum. If a change breaks one of your applications, please file a ticket and let us know.
Hopefully this answered all of your questions. If I missed something, let me know.
-- Trevor Johns
On Wed, Jul 9, 2008 at 12:47 PM, DHager <hage...@gmail.com> wrote:
> P.S: And these confusing special-case rules were all slightly > different just a month or so ago.
> "Fax" wasn't treated specially compared to "Mobile". "Personal" didn't > map to rel=*#home, it was just rel=*#personal instead... etc.
Having to check rel vs label won't be changing, however. The reason this is done is so that common categories have a language-independent way to perform comparisons. Label tags can be in any language, rel tags will always be in english.
In order to help make sure that the rel tags do not fluctuate any more, I've filed another ticket to have these explicitly documented: