Re: v3 cc api style guide feedback requested

Guillaume Berche

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*s*
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)> wrote:

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

Join { to automatically receive all group messages.