Specification for handling response status

[Li]

Hi,

The Portable Contact spec does not seem to specify any details on how
to pass the server response status to the client. I tentatively add
some customized status fields in the reply. See below.

"statusCode": 200,
"statusText": Ok,
"statusDetailCode": 0,
"requestId": 1253731195989,
"accountId": aolUser1,
"lcn": 29,

I would like to know the standard way to handle the application
response code in Poco.

Thanks

{
"statusCode": 200,
"statusText": Ok,
"statusDetailCode": 0,
"requestId": 1253731195989,
"accountId": aolUser1,
"lcn": 29,

"startIndex": 0,
"itemsPerPage": 1,
"totalResults": 1,
{
"id": "7038",
"displayName": "1980-01-01",
"name": {
"familyName": "Runningman",
"givenName": "AOL"
},
"birthday": "1980-01-01",
"gender": "M",
"tags": [
"AOL member",
"Runningman"
],
"emails": [
{
"value": "runni...@aol.com",
"type": "work",
"primary": "true",
"tags": "1"
},
{
"value": "runni...@yahoo.com",
"type": "home",
"tags": "2"
}
],
"urls": [
{
"value": "http://dev.aol.com",
"type": "work"
}
],
"phoneNumbers": [
{
"value": "7032653362",
"type": "work",
"primary": "true",
"tags": "1"
},
{
"value": "703-404-9876",
"type": "mobile",
"tags": "2"
}
],
"ims": [
{
"value": "runningman",
"type": "aim"
}
],
"addresses": [
{
"type": "home",
"streetAddress": "12000 AOL Way",
"locality": "Dulles",
"region": "VA",
"postalCode": "20166",
"country": "USA",
"formatted": "12000 AOL Way\nDulles, VA 20166 USA"
}
],
"organizations": [
{
"name": "AOL",
"title": "icon"
}
]
}
]
}

[Joseph Smarr]

Interesting, I guess we never specified the specific response parameters to use when including the HTTP response code, even though we say to do so in section 6 and 6.5. Good catch! :)

I think I had in mind something a but shorter like "code" for the HTTP response code, and "reason" for the explanatory text. I think the rest of the stuff you've provided is reasonable to add, but not necessary to be in the spec (the main point of interop should be knowing what the error code was and having some text string associated with it). Does that sound reasonable to you?

Anyone else have an opinion on this, or have prior art to point to?

Thanks, js

--
You received this message because you are subscribed to the Google Groups "PortableContacts" group.
To post to this group, send email to portable...@googlegroups.com.
To unsubscribe from this group, send email to portablecontac...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/portablecontacts?hl=en.

[Li]

My point is that the generic HTTP response code is more of transport
level which does not necessarily tell the client about application
level health. The 'shorter like' code and reason would be helpful.

If interop is an issue, my suggestion is to add some-kinda generic
extension fields in the poco spec just like the vCard extension
fields.

On Feb 1, 10:48 am, Joseph Smarr <jsm...@gmail.com> wrote:
> Interesting, I guess we never specified the specific response parameters to
> use when including the HTTP response code, even though we say to do so in
> section 6 and 6.5. Good catch! :)
>
> I think I had in mind something a but shorter like "code" for the HTTP
> response code, and "reason" for the explanatory text. I think the rest of
> the stuff you've provided is reasonable to add, but not necessary to be in
> the spec (the main point of interop should be knowing what the error code
> was and having some text string associated with it). Does that sound
> reasonable to you?
>
> Anyone else have an opinion on this, or have prior art to point to?
>
> Thanks, js
>

> >         "value": "running...@aol.com",

> >         "type": "work",
> >         "primary": "true",
> >         "tags": "1"
> >       },
> >       {

> >         "value": "running...@yahoo.com",

> > portablecontac...@googlegroups.com<portablecontacts%2Bunsu...@googlegroups.com>
> > .

[JBJ]

The server response would be available via the HTTP Headers.

The Portable Contact spec does state in Section 6 (http://portablecontacts.net/draft-spec.html#anchor7) that :

"Response and error codes SHOULD be transmitted via the HTTP status code of the response (if possible), and SHOULD also be specified in the body of the response, as described in Section 6.4 and Section 6.5. "

Surely the success response is the presence of a Portable Contacts 'response' object with the minimum required fields in addition to the HTTP Status Code on the header response. 

Does the success message body need status information duplicated that can be carried in the header?

The description of what a human readable error message might be in a response body needs expanding if a non 200 code is returned.

Cheers,

Jonathan

--
You received this message because you are subscribed to the Google Groups "PortableContacts" group.
To post to this group, send email to portable...@googlegroups.com.

To unsubscribe from this group, send email to portablecontac...@googlegroups.com.

[Joseph Smarr]

Yeah, the idea was that it's convenient for developers to get response codes in the response body, since a) they can see it in the browser, b) they can parse it out of the response without separately having to look at the HTTP headers and response codes (which are often more complex to get via code and require having a handle to the curl object instead of just the response body), and c) some servers find it easier to return an HTTP 200 even though they put application-level error data in the response (e.g. invalid field to filter on). So that's why we settled on "providers SHOULD use HTTP response codes, and SHOULD ALSO put them in the body for convenience".

[Li]

I think that the detail status info in the body should not cause
interop issues if they are generic enough. The example I have is
coming from Aol open services standard.

"statusCode": 200,
"statusText": Ok,
"statusDetailCode": 0,
"requestId": 1253731195989,

Can we work on standardize them and add it to the spec? We are
currently implementing Poco as our future api standard. I would like
to see it defined quickly.

Thanks
Li

On Feb 1, 1:26 pm, Joseph Smarr <jsm...@gmail.com> wrote:
> Yeah, the idea was that it's convenient for developers to get response codes
> in the response body, since a) they can see it in the browser, b) they can
> parse it out of the response without separately having to look at the HTTP
> headers and response codes (which are often more complex to get via code and
> require having a handle to the curl object instead of just the response
> body), and c) some servers find it easier to return an HTTP 200 even though
> they put application-level error data in the response (e.g. invalid field to
> filter on). So that's why we settled on "providers SHOULD use HTTP response
> codes, and SHOULD ALSO put them in the body for convenience".
>

> On Tue, Feb 1, 2011 at 7:56 AM, JBJ <juniorbadger...@gmail.com> wrote:
> > The server response would be available via the HTTP Headers.
> > The Portable Contact spec does state in Section 6 (
> >http://portablecontacts.net/draft-spec.html#anchor7) that :
>
> > "Response and error codes SHOULD be transmitted via the HTTP status code of
> > the response (if possible), and SHOULD also be specified in the body of the

> > response, as described in Section 6.4<http://portablecontacts.net/draft-spec.html#response-format>
> >  and Section 6.5 <http://portablecontacts.net/draft-spec.html#error-codes>
> > . "

>
> > Surely the success response is the presence of a Portable Contacts
> > 'response' object with the minimum required fields in addition to the HTTP
> > Status Code on the header response.
> > Does the success message body need status information duplicated that can
> > be carried in the header?
>
> > The description of what a human readable error message might be in a
> > response body needs expanding if a non 200 code is returned.
>
> > Cheers,
> > Jonathan
>

> >>         "value": "running...@aol.com",

> >>         "type": "work",
> >>         "primary": "true",
> >>         "tags": "1"
> >>       },
> >>       {

> >>         "value": "running...@yahoo.com",

> >> portablecontac...@googlegroups.com<portablecontacts%2Bunsu...@googlegroups.com>
> >> .

> >> For more options, visit this group at
> >>http://groups.google.com/group/portablecontacts?hl=en.
>
> >  --
> > You received this message because you are subscribed to the Google Groups
> > "PortableContacts" group.
> > To post to this group, send email to portable...@googlegroups.com.
> > To unsubscribe from this group, send email to

> > portablecontac...@googlegroups.com<portablecontacts%2Bunsu...@googlegroups.com>
> > .

[Joseph Smarr]

Li-are you saying you can't easily output anything other than those exact field names, or just that you'd like to be able to output those fields as part of your response? You're certainly free to do the latter either way (the spec doesn't say "these are the only fields you can ever output", just "if you're outputting standard fields, please use these names for maximum interop"). For the former, of course every provider is going to output names slightly differently based on their internal tools, but that's exactly why we need a standard for the common fields, and with PoCo we've tried very hard to keep things as clean, simple, and intuitive as possible. 

For response codes, again unless people feel strongly otherwise, I think "code" and "reason" should be plenty to standardize (again with providers still free to return additional data). I don't feel too strongly about the exact names, but e.g. I'd worry a bit that "statusText" sounds a bit like the PoCo field "status" which is the user's latest status message. If we were going to use the exact terms that HTTP does, it would be "statusCode" and "reasonPhrase" (see http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html), so my suggestion was "code" and "reason" to echo those but keep it a bit tighter.

Does that make sense and work for your implementation?

Anyone else wanna weigh in on this?

Thanks, js

To unsubscribe from this group, send email to portablecontac...@googlegroups.com.

[George Fletcher]

Hi Joseph,

I think that 'code' and 'reason' are sufficient for what we need. Within the AOL Open Services, we track message response separate from HTTP response code because in some cases the message is successfully delivered to the server but there is a processing error. For Flash based clients it's very difficult to get the HTTP response codes, so we return a HTTP 200 and then put the server error code in the body of the message. Praveen and I wrote an extension for OAuth 1.0 to deal with this as well... it just never got any adoption.

A couple other questions...

1. I noticed in the change log for the spec that JSONP support was explicitly removed. Would you mind recounting what the security issues are? Is this something within the opensocial environment?

2. For XML responses, is the xschema flexible enough to allow providers to return additional fields (i.e. appropriately sprinkled with xsany :). Or does PoCo not really have a schema definition?

Thanks,
George

-- 
Chief Architect                   AIM:  gffletch
Identity Services Engineering     Work: george....@teamaol.com
AOL Inc.                          Home: gffl...@aol.com
Mobile: +1-703-462-3494           Blog: http://practicalid.blogspot.com
Office: +1-703-265-2544           Twitter: http://twitter.com/gffletch

[Joseph Smarr]

Hi George, sounds good! 

I originally had JSONP support in PoCo, but the OpenSocial guys (MySpace in particular) wanted me to take it out, I believe because in order to make OAuth1-signed requested from the user-agent, you'd have to have the consumer secret in the clear (or, at least, it might encourage un-savvy developers to do that). Of course that doesn't stop you from providing JSONP support if you're comfortable with it, but since the aspiration of PoCo was to work with "any provider, even if you've never heard of them before", it didn't make sense to "promise" JSONP if some (large, at least at the time) providers weren't going to support it. IMO, it's still very useful, and esp. for public data (no signing issue there). Plus if/when we move PoCo to support OAuth2, then it seems reasonable to allow JSONP with bearer tokens. So in any case, please don't let this stop you from shipping your endpoint or from supporting JSONP if you want!

And yes, feel free to add whatever additional fields you want to the JSON or XML. We didn't specify a formal namespace or schema for PoCo because we didn't see it being necessary in practice for most developers, and we were trying to stay as simple as possible. But we did break out the schema with a namespace in http://portablecontacts.net/draft-schema.html for embedding in XRD or similar contexts, so feel free to use that if it's helpful.

Thanks! js

[justin kruger]

Yahoo keeps flopping back and forth on whether they support JSONP
callbacks on api calls.
Sometimes I just use YQL to get around that little side note.

On the REST Status side, it might be nice to specify what all of the
4xx response codes mean when related to PoCo.

For instance a 401 and a 403 both relate to auth, and the original
http spec seems to relate to basic auth, however it would be nice to
have a constant standard in this modern age.

For PoCo I could see a use for 400, 401, 403, 404, 405, 407, 409

400=>'400 Bad Request', //missing params, cookies, or tokens
401=>'401 Unauthorized', //wrong credentials
402=>'402 Payment Required',
403=>'403 Forbidden', //these credentials are not allowed
404=>'404 Not Found', //no data found
405=>'405 Method Not Allowed', //?
406=>'406 Not Acceptable', //?
407=>'407 Proxy Authentication Required', //? delegated
or proxies auth request failed, ie.. opensocial makeRequest
408=>'408 Request Timeout',
409=>'409 Conflict', //?in this case i am using it
for registration, if that ID has been taken, but i could see this on
contact import too
410=>'410 Gone',
411=>'411 Length Required',
412=>'412 Precondition Failed',
413=>'413 Request Entity Too Large',
414=>'414 Request-URI Too Long',
415=>'415 Unsupported Media Type', //when uploading photos,
or submitting json or xml post/ put bodies
416=>'416 Requested Range Not Satisfiable',
417=>'417 Expectation Failed',
// [Server Error 5xx]
500=>'500 Internal Server Error',
501=>'501 Not Implemented',
502=>'502 Bad Gateway',
503=>'503 Service Unavailable',
504=>'504 Gateway Timeout',
505=>'505 HTTP Version Not Supported'

--
--
--
Justin Kruger
Social Media Software Engineer -
San Francisco, CA

--
http://twitter.com/jdavid
http://www.linkedin.com/in/jdavid

[Li]

It turns out the <code> is a standard HTML tag. Do you think it is
going to cause any issue? If Yes, Do you have any other idea on the
name for this purpose?

> > On Tue, Feb 1, 2011 at 11:58 AM, Li <lincre...@aol.com
> > <mailto:lincre...@aol.com>> wrote:
>
> >     I think that the detail status info in the body should not cause
> >     interop issues if  they are generic enough. The example I have is
> >     coming from Aol open services standard.
>
> >     "statusCode": 200,
> >      "statusText": Ok,
> >      "statusDetailCode": 0,
> >      "requestId": 1253731195989,
>
> >     Can we work on standardize them and add it to the spec?  We are
> >     currently implementing Poco as our future api standard. I would like
> >     to see it defined quickly.
>
> >     Thanks
> >     Li
>
> >     On Feb 1, 1:26 pm, Joseph Smarr <jsm...@gmail.com

> >     <mailto:jsm...@gmail.com>> wrote:
> >     > Yeah, the idea was that it's convenient for developers to get
> >     response codes
> >     > in the response body, since a) they can see it in the browser,
> >     b) they can
> >     > parse it out of the response without separately having to look
> >     at the HTTP
> >     > headers and response codes (which are often more complex to get
> >     via code and
> >     > require having a handle to the curl object instead of just the
> >     response
> >     > body), and c) some servers find it easier to return an HTTP 200
> >     even though
> >     > they put application-level error data in the response (e.g.
> >     invalid field to
> >     > filter on). So that's why we settled on "providers SHOULD use
> >     HTTP response
> >     > codes, and SHOULD ALSO put them in the body for convenience".
>
> >     > On Tue, Feb 1, 2011 at 7:56 AM, JBJ <juniorbadger...@gmail.com

> >     <mailto:running...@aol.com>",

> >     > >>         "type": "work",
> >     > >>         "primary": "true",
> >     > >>         "tags": "1"
> >     > >>       },
> >     > >>       {
> >     > >>         "value": "running...@yahoo.com

> >     <mailto:running...@yahoo.com>",

> >     <mailto:portable...@googlegroups.com>.

> >     > >> To unsubscribe from this group, send email to
> >     > >> portablecontac...@googlegroups.com

> >     <mailto:portablecontacts%2Bunsu...@googlegroups.com><portablecontacts%2Bunsu...@googlegroups.com
> >     <mailto:portablecontacts%252Buns...@googlegroups.com>>

> >     > >> .
> >     > >> For more options, visit this group at
> >     > >>http://groups.google.com/group/portablecontacts?hl=en.
>
> >     > >  --
> >     > > You received this message because you are subscribed to the
> >     Google Groups
> >     > > "PortableContacts" group.
> >     > > To post to this group, send email to
> >     portable...@googlegroups.com

> >     <mailto:portable...@googlegroups.com>.

> >     > > To unsubscribe from this group, send email to
> >     > > portablecontac...@googlegroups.com

> >     <mailto:portablecontacts%2Bunsu...@googlegroups.com><portablecontacts%2Bunsu...@googlegroups.com
> >     <mailto:portablecontacts%252Buns...@googlegroups.com>>

> >     > > .
> >     > > For more options, visit this group at
> >     > >http://groups.google.com/group/portablecontacts?hl=en.
>
> >     --
> >     You received this message because you are subscribed to the Google
> >     Groups "PortableContacts" group.
> >     To
>

> ...
>
> read more »

[Joseph Smarr]

Shouldn't be a problem because you're not embedding this PoCo output in normal HTML anyway. Thanks, js

To post to this group, send email to portable...@googlegroups.com.
To unsubscribe from this group, send email to portablecontac...@googlegroups.com.