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
contacts system.

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:

    <gd:email rel='http://schemas.google.com/g/2005#work'
address='test1.fakew...@example.com' />
    <gd:email rel='http://schemas.google.com/g/2005#work'
address='test...@example.com' />

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
"mobile".

    <gd:phoneNumber rel='http://schemas.google.com/g/2005#work'> (123)
555-1001 </gd:phoneNumber>
    <gd:phoneNumber label='Work / Mobile'>        (123) 555-1002 </
gd:phoneNumber>
    <gd:phoneNumber label='Work / Pager'> (123) 555-1003 </
gd:phoneNumber>
    <gd:phoneNumber rel='http://schemas.google.com/g/
2005#work_fax'>(123) 555-1004 </gd:phoneNumber>

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.

<-- No category -->
<gd:email rel='http://schemas.google.com/g/2005#other'
address='te...@example.com' primary='true' />
<-- "Work" -->
gd:email rel='http://schemas.google.com/g/2005#work'
address='test...@example.com' />
<-- "Personal" -->
<gd:email rel='http://schemas.google.com/g/2005#home'
address='t...@personal.example.com' />
<-- "home" -->
<gd:email label='home' address='test@home_lowercase.example.com' />
<-- "Home" -->
<gd:email label='Home' address='t...@home.example.com' />
<!-- "MyCat" -->
<gd:email label='MyCat' address='t...@mycat.example.com' />
<!-- "Other" -->
<gd:email rel='http://schemas.google.com/g/2005#other'
address='t...@other.example.com' />
<!-- "other" -->
<gd:email label='other' address='test@other_lowercase.example.com' />

What does this tell us?

When "rel=*#other", it means the category "Other" or the no-category
primary address.
The category "other" in lowercase however means we look at the label
attribute.
The category "Personal" maps to looking for rel=$#home
But the category "Home" or "home" actually means we look inside the
label...
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.

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.

So to rephrase this as a direct request:

support for the API in PHP (Zend Framework).
Is something being done about these issues?
Am I just missing some piece of information?

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:

http://code.google.com/p/gdata-issues/issues/detail?id=639

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

--
Trevor Johns

While I can't comment on specifics regarding potential future
releases, this is on our radar and something we're very interested in
seeing added to the framework.

--
Trevor Johns

I'm sorry, I think I mangled one of my messages an erased a line
before "support for the API".

The reason I'm asking about this is because I'm the one (one-of-the-
ones?) writing support for the Contacts Data API into the Zend
Framework. Hence all the complaints about what the raw XML.

Ah, that makes a lot more sense.

Not handling duplicate category names properly and the inability to
preserve groupings from the GMail UI doesn't seem right, and I've
filed a ticket to have this looked into.

    http://code.google.com/p/gdata-issues/issues/detail?id=639

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:

    http://code.google.com/p/gdata-issues/issues/detail?id=653

Let me know if I missed any of your questions/comments.

(Also, sorry for the delay in responding, I was discussing this with
some of the other engineers.)

--
Trevor Johns