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. 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
https://github.com/swagger-api/swagger-codegen/issues/325 )

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
https://github.com/cloudfoundry/cli/issues/560

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
https://github.com/cloudfoundry/cc-api-v3-style-guide/issues/2 ).

https://github.com/cloudfoundry/cc-api-v3-style-guide#pagination
*"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

https://github.com/cloudfoundry/cc-api-v3-style-guide#query-parameters
Precise character escaping on query param values e.g. containing comma:
filtering on name="a,b"


https://github.com/cloudfoundry/cc-api-v3-style-guide#pagination-of-related-resources

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

with pluralized resource name should be GET /v3/apps/:guid?include=space
*s*,organization*s*


https://github.com/cloudfoundry/cc-api-v3-style-guide#pagination-of-related-resources
would be nice to include an example of a pagination request on a related
resource inclusion request (e.g,

/v2/spaces/ab09cd29-9420-f021-g20d-123431420768?include=apps&*include_apps_order_by*=-state,-date)

https://github.com/cloudfoundry/cc-api-v3-style-guide#proposal
Would useful to consider I18N of user-facing messages. Cf related thread
for service broker error messages at
http://cf-dev.70369.x6.nabble.com/cf-dev-Announcing-Experimental-support-for-Asynchronous-Service-Operations-tp287p1471.html
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.

Thanks,

Guillaume.

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