Response codes using REST protocol
77 views
Skip to first unread message
Laurent-Walter Goix
Mar 2, 2012, 9:22:58 AM3/2/12
to OpenSocial and Gadgets Specification Discussion
Hello all,
going through the spec (Social API & Core API) i couldn't find clear
statements regarding the response codes to be returned. i would assume
some flexibility of course but also some more precise guidelines.
for example, i would assume that when creating a resource, a 201
answer would returned, with the json object newly created + a Location
header. this could happen when creating an activity, or a one-way
relationship that does not need acceptance.interestingly when creating
activities a return-object: null is mentioned as the only option.
in other cases, a 202 may be preferable (with no body probably) to
indicate that the requests was accepted but some processing still need
to be done (e.g. friendship request)
yet in other cases some error may appear that could trigger http error
codes. i am also wondering if some more specific errors are needed
(e.g. to indicate missing parameters in the object provided by the
client, etc)
is there any plan to check to whole social api spec service by service
and revise the return object, further providing some generic
guidelines in the core api spec about response codes for rest?
thank you
walter
going through the spec (Social API & Core API) i couldn't find clear
statements regarding the response codes to be returned. i would assume
some flexibility of course but also some more precise guidelines.
for example, i would assume that when creating a resource, a 201
answer would returned, with the json object newly created + a Location
header. this could happen when creating an activity, or a one-way
relationship that does not need acceptance.interestingly when creating
activities a return-object: null is mentioned as the only option.
in other cases, a 202 may be preferable (with no body probably) to
indicate that the requests was accepted but some processing still need
to be done (e.g. friendship request)
yet in other cases some error may appear that could trigger http error
codes. i am also wondering if some more specific errors are needed
(e.g. to indicate missing parameters in the object provided by the
client, etc)
is there any plan to check to whole social api spec service by service
and revise the return object, further providing some generic
guidelines in the core api spec about response codes for rest?
thank you
walter
James M Snell
Mar 2, 2012, 9:52:43 AM3/2/12
to opensocial-an...@googlegroups.com
Yes, this is one of the things that I already have on my todo list for the editorial updates. I haven't opened an issue for it yet tho.
--
You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
To post to this group, send email to opensocial-an...@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.
Laurent-Walter Goix
Jun 13, 2012, 6:33:55 AM6/13/12
to opensocial-an...@googlegroups.com
Hello James,
any news on that side? i have noticed the issue 1308 [1] (and proposal) related to error representations for the next APIs (including REST). Some spec patches also mention 2xx response codes here and there to clarify the possible use cases, but i haven't seen any dedicated section so far on that topic that would ease the understanding (and implementation) of the spec.
walter
[1] http://code.google.com/p/opensocial-resources/issues/detail?id=1308
any news on that side? i have noticed the issue 1308 [1] (and proposal) related to error representations for the next APIs (including REST). Some spec patches also mention 2xx response codes here and there to clarify the possible use cases, but i haven't seen any dedicated section so far on that topic that would ease the understanding (and implementation) of the spec.
walter
[1] http://code.google.com/p/opensocial-resources/issues/detail?id=1308
To post to this group, send email to opensocial-and-gadgets-spec@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadgets-spec+unsub...@googlegroups.com.
James M Snell
Jun 13, 2012, 10:38:11 AM6/13/12
to opensocial-an...@googlegroups.com
I have not yet fully addressed this issue as far as dealing with
specific response codes. General updates have been made in the 3.0
draft core-api spec (in the repo) but they are, as yet, incomplete.
On Wed, Jun 13, 2012 at 3:33 AM, Laurent-Walter Goix
>>> opensocial-an...@googlegroups.com.
> https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/MO82oOY7gGMJ.
specific response codes. General updates have been made in the 3.0
draft core-api spec (in the repo) but they are, as yet, incomplete.
On Wed, Jun 13, 2012 at 3:33 AM, Laurent-Walter Goix
>>> To unsubscribe from this group, send email to
>>> opensocial-and-gadg...@googlegroups.com.
>>> For more options, visit this group at
>>> http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.
>>>
>>> http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.
>>>
> --
> You received this message because you are subscribed to the Google Groups
> "OpenSocial and Gadgets Specification Discussion" group.
> To view this discussion on the web visit
> You received this message because you are subscribed to the Google Groups
> "OpenSocial and Gadgets Specification Discussion" group.
> https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/MO82oOY7gGMJ.
>
> To post to this group, send email to
> opensocial-an...@googlegroups.com.
> To post to this group, send email to
> To unsubscribe from this group, send email to
> opensocial-and-gadg...@googlegroups.com.
Laurent-Walter Goix
Jun 20, 2012, 10:44:04 AM6/20/12
to OpenSocial and Gadgets Specification Discussion
for 2.5 i would thus recommend to update at least section 2.1.2.1 of
the core API spec that currently says:
REST-Response-Payload = "<response xmlns='http://ns.opensocial.org/
2008/opensocial'>"
Return-Object
"</response>"
i believe most of these payloads are actually JSON rather than XML...
walter
On Jun 13, 4:38 pm, James M Snell <jasn...@gmail.com> wrote:
> I have not yet fully addressed this issue as far as dealing with
> specific response codes. General updates have been made in the 3.0
> draft core-api spec (in the repo) but they are, as yet, incomplete.
>
> On Wed, Jun 13, 2012 at 3:33 AM, Laurent-Walter Goix
>
>
>
>
>
>
>
> <laurentwalter.g...@gmail.com> wrote:
> > Hello James,
>
> > any news on that side? i have noticed the issue 1308 [1] (and proposal)
> > related to error representations for the next APIs (including REST). Some
> > spec patches also mention 2xx response codes here and there to clarify the
> > possible use cases, but i haven't seen any dedicated section so far on that
> > topic that would ease the understanding (and implementation) of the spec.
>
> > walter
>
> > [1]http://code.google.com/p/opensocial-resources/issues/detail?id=1308
>
> > Il giorno venerdì 2 marzo 2012 15:52:43 UTC+1, James M Snell ha scritto:
>
> >> Yes, this is one of the things that I already have on my todo list for the
> >> editorial updates. I haven't opened an issue for it yet tho.
>
> >> On Mar 2, 2012 6:22 AM, "Laurent-Walter Goix"
> >https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/MO82oOY....
the core API spec that currently says:
REST-Response-Payload = "<response xmlns='http://ns.opensocial.org/
2008/opensocial'>"
Return-Object
"</response>"
i believe most of these payloads are actually JSON rather than XML...
walter
On Jun 13, 4:38 pm, James M Snell <jasn...@gmail.com> wrote:
> I have not yet fully addressed this issue as far as dealing with
> specific response codes. General updates have been made in the 3.0
> draft core-api spec (in the repo) but they are, as yet, incomplete.
>
> On Wed, Jun 13, 2012 at 3:33 AM, Laurent-Walter Goix
>
>
>
>
>
>
>
> <laurentwalter.g...@gmail.com> wrote:
> > Hello James,
>
> > any news on that side? i have noticed the issue 1308 [1] (and proposal)
> > related to error representations for the next APIs (including REST). Some
> > spec patches also mention 2xx response codes here and there to clarify the
> > possible use cases, but i haven't seen any dedicated section so far on that
> > topic that would ease the understanding (and implementation) of the spec.
>
> > walter
>
> > [1]http://code.google.com/p/opensocial-resources/issues/detail?id=1308
>
> > Il giorno venerdì 2 marzo 2012 15:52:43 UTC+1, James M Snell ha scritto:
>
> >> Yes, this is one of the things that I already have on my todo list for the
> >> editorial updates. I haven't opened an issue for it yet tho.
>
> >> On Mar 2, 2012 6:22 AM, "Laurent-Walter Goix"
Matthew Marum
Jun 20, 2012, 2:16:33 PM6/20/12
to opensocial-an...@googlegroups.com
Right, the JSON equivalent looks something like
response : Return-Object
We should probably just document that the "Return Object is enclosed by the 'response' property or element within REST responses"
Matt
> >>> opensocial-and-gadgets-spec@googlegroups.com.
> >>> To unsubscribe from this group, send email to
> >>> opensocial-and-gadgets-spec+unsub...@googlegroups.com.
> >>> For more options, visit this group at
> >>>http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.
>
> > --
> > You received this message because you are subscribed to the Google Groups
> > "OpenSocial and Gadgets Specification Discussion" group.
> > To view this discussion on the web visit
> >https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/MO82oOY....
>
> > To post to this group, send email to
> > opensocial-and-gadgets-spec@googlegroups.com.
> > To unsubscribe from this group, send email to
> > opensocial-and-gadgets-spec+unsub...@googlegroups.com.
Laurent-Walter Goix
Jun 21, 2012, 2:02:37 PM6/21/12
to OpenSocial and Gadgets Specification Discussion
Or it could say:
REST-Response-Payload = Return-object / "error": RPC-Error
Despite its name RPC-error definition suits actually quite well
application-level errors in json with rest as well.
Return-object already includes "entry": and the like for collections
etc so it may not need an additional encapsulation.
What do you think?
On 20 juin, 20:16, Matthew Marum <mgma...@gmail.com> wrote:
> Right, the JSON equivalent looks something like
>
> response : Return-Object
>
> We should probably just document that the "Return Object is enclosed by the
> 'response' property or element within REST responses"
>
> Matt
>
>
>
>
>
>
>
> On Wednesday, June 20, 2012 10:44:04 AM UTC-4, Laurent-Walter Goix wrote:
>
> > for 2.5 i would thus recommend to update at least section 2.1.2.1 of
> > the core API spec that currently says:
>
> > REST-Response-Payload = "<response xmlns='http://ns.opensocial.org/
> > 2008/opensocial <http://ns.opensocial.org/2008/opensocial>'>"
> > > >>> opensocial-an...@googlegroups.com.
REST-Response-Payload = Return-object / "error": RPC-Error
Despite its name RPC-error definition suits actually quite well
application-level errors in json with rest as well.
Return-object already includes "entry": and the like for collections
etc so it may not need an additional encapsulation.
What do you think?
On 20 juin, 20:16, Matthew Marum <mgma...@gmail.com> wrote:
> Right, the JSON equivalent looks something like
>
> response : Return-Object
>
> We should probably just document that the "Return Object is enclosed by the
> 'response' property or element within REST responses"
>
> Matt
>
>
>
>
>
>
>
> On Wednesday, June 20, 2012 10:44:04 AM UTC-4, Laurent-Walter Goix wrote:
>
> > for 2.5 i would thus recommend to update at least section 2.1.2.1 of
> > the core API spec that currently says:
>
> > REST-Response-Payload = "<response xmlns='http://ns.opensocial.org/
> > > >>> To unsubscribe from this group, send email to
> > > >>> opensocial-and-gadg...@googlegroups.com.
> > > >>> For more options, visit this group at
> > > >>>http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.
>
> > > > --
> > > > You received this message because you are subscribed to the Google
> > Groups
> > > > "OpenSocial and Gadgets Specification Discussion" group.
> > > > To view this discussion on the web visit
> > > >https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/MO82oOY....
>
> > > > To post to this group, send email to
> > > > opensocial-an...@googlegroups.com.
> > > >>>http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.
>
> > > > --
> > > > You received this message because you are subscribed to the Google
> > Groups
> > > > "OpenSocial and Gadgets Specification Discussion" group.
> > > > To view this discussion on the web visit
> > > >https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/MO82oOY....
>
> > > > To post to this group, send email to
> > > > To unsubscribe from this group, send email to
> > > > opensocial-and-gadg...@googlegroups.com.
Matthew Marum
Jun 21, 2012, 2:27:03 PM6/21/12
to opensocial-an...@googlegroups.com
I agree that the 'response' encapsulation may not be needed but I THINK that's what Shindig uses so I'm not sure if there's good reason to change it now. I'm going to test it in Shindig and see what it does.
Matt
> > > >>> opensocial-and-gadgets-spec@googlegroups.com.
> > > >>> To unsubscribe from this group, send email to
> > > >>> For more options, visit this group at
> > > >>>http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.
>
> > > > --
> > > > You received this message because you are subscribed to the Google
> > Groups
> > > > "OpenSocial and Gadgets Specification Discussion" group.
> > > > To view this discussion on the web visit
> > > >https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/MO82oOY....
>
> > > > To post to this group, send email to
> > > > To unsubscribe from this group, send email to
Matthew Marum
Jun 21, 2012, 3:06:04 PM6/21/12
to opensocial-an...@googlegroups.com
Tested it and it looks like Shindig does what you suggested. Example of a successful JSON response...
{
"entry": {
"name": {
"givenName": "John",
"formatted": "John Doe",
"familyName": "Doe"
},
"id": "john.doe"
}
}
Laurent-Walter Goix
Jun 22, 2012, 2:56:39 AM6/22/12
to OpenSocial and Gadgets Specification Discussion
Indeed i checked myself first :)
What shindig does not is json for errors (returns strings) but it may
be easy and cleaner to promote a json format probably instead at least
from spec point of view. Clarifying this in 2.5 with a simple
statement could be an easy first step IMO (notwithstanding the odd
reference to RPC from rest :) )
Of course other proposals are welcome. What I believe is important is
to formally update this description as this is now outdated.
Walter
What shindig does not is json for errors (returns strings) but it may
be easy and cleaner to promote a json format probably instead at least
from spec point of view. Clarifying this in 2.5 with a simple
statement could be an easy first step IMO (notwithstanding the odd
reference to RPC from rest :) )
Of course other proposals are welcome. What I believe is important is
to formally update this description as this is now outdated.
Walter
Laurent-Walter Goix
Sep 3, 2012, 11:34:52 AM9/3/12
to opensocial-an...@googlegroups.com
As this is still pending i filed the related issue:
http://code.google.com/p/opensocial-resources/issues/detail?id=1326
http://code.google.com/p/opensocial-resources/issues/detail?id=1326
Reply all
Reply to author
Forward
0 new messages