Re: v3 cc api style guide feedback requested

Guillaume Berche

On Wed, Sep 9, 2015 at 10:39 AM, Dieu Cao <dcao(a)> wrote:

Hi Guillaume,

Just to ensure that it will be addressed, could you add it as github
issues on the repo? Hoping to do another pass at the remaining open issues
later this week.


On Mon, Sep 7, 2015 at 2:09 PM, Guillaume Berche <bercheg(a)>

Thanks for sharing this great spec.

Not sure if you're preferring feedback other the mailing list of GH
issue. Let me know.

General feedback:

+1 for a formal schema for the v3 api as to ease automatic client
generations (api explorer, java sdk, go sdk...) (e.g. swagger format)
Automated tests on the formal schema may also help checking the style guide
is respected. seems
to only consider documentation benefits so far and not yet client
generation benefits (e.g. )

Would be nice to clarify support for non ascii characters in query
params, such as support for IRI as
to avoid mojibake bugs such as the one presumed in

Would be nice to consider supporting gzip encoding for the json payload
responses as to speed up responses over internet connections
('Accept-Encoding' header)

It general it may make sense to clarify supported HTTP headers (+1 for
etag/if-modified-since support suggested at ).
*"order_by: a field on the resource to order the collection by; each
collection may choose a subset of fields that it can be sorted by "*

Would be nice to illustrate/precise if multiple sort order can be
supported, e.g. order_by=-state,-created
Precise character escaping on query param values e.g. containing comma:
filtering on name="a,b"

GET /v3/apps/:guid?include=space,organization

with pluralized resource name should be GET /v3/apps/:guid?include=space
would be nice to include an example of a pagination request on a related
resource inclusion request (e.g,

Would useful to consider I18N of user-facing messages. Cf related thread
for service broker error messages at
May be the CC API could accept a "Accept-Language: zh_Hans" header and
try to return localized messages when available in the accepted locale.



On Wed, Sep 2, 2015 at 6:44 PM, Zach Robinson <zrobinson(a)>

Thanks James, I've just corrected the three issues you've noted so far

Join to automatically receive all group messages.