- v3 cc api style guide feedback requested
Re: v3 cc api style guide feedback requested
toggle quoted messageShow quoted text
On Wed, Sep 9, 2015 at 2:33 PM, Guillaume Berche <bercheg(a)gmail.com> wrote:
Here are corresponding issues/comments submitted
On Wed, Sep 9, 2015 at 10:39 AM, Dieu Cao <dcao(a)pivotal.io> wrote:
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)gmail.com>
Thanks for sharing this great spec.
Not sure if you're preferring feedback other the mailing list of GH
issue. Let me know.
+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. https://www.pivotaltracker.com/story/show/99237980 seems
to only consider documentation benefits so far and not yet client
generation benefits (e.g. https://github.com/swagger-api/swagger-codegen
Would be nice to clarify support for non ascii characters in query
params, such as support for IRI
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
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"
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)pivotal.io>
Thanks James, I've just corrected the three issues you've noted so far
Join email@example.com to automatically receive all group messages.