Re: v3 cc api style guide feedback requested
Thanks for sharing this great spec.toggle quoted messageShow quoted text
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
https://en.wikipedia.org/wiki/Internationalized_resource_identifier 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
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*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)pivotal.io> wrote:
Thanks James, I've just corrected the three issues you've noted so far