Date
1 - 9 of 9
v3 cc api style guide feedback requested
|
Dieu Cao <dcao@...>
Hi All,
The CAPI team has created a style guide for v3 of the cloud controller api and would like to share this again with the wider cf community for feedback after initial review within the team. [1] Issues/PRs are welcome and appreciated! Thanks, Dieu CF CAPI PM [1] https://github.com/cloudfoundry/cc-api-v3-style-guide |
|
|
|
James Bayer
should the PUT example that updates the app name and space guid actually be
toggle quoted message
Show quoted text
a PATCH since it updates the resource? https://github.com/cloudfoundry/cc-api-v3-style-guide#put On Wed, Sep 2, 2015 at 1:40 AM, Dieu Cao <dcao(a)pivotal.io> wrote:
Hi All, --
Thank you, James Bayer |
|
|
|
James Bayer
the collections example [1] does not actually include the required
toggle quoted message
Show quoted text
*resources* field [1] https://github.com/cloudfoundry/cc-api-v3-style-guide#example-2 On Wed, Sep 2, 2015 at 8:16 AM, James Bayer <jbayer(a)pivotal.io> wrote:
should the PUT example that updates the app name and space guid actually --
Thank you, James Bayer |
|
|
|
James Bayer
the example used for actions uses the v2 api instead of v3:
toggle quoted message
Show quoted text
https://github.com/cloudfoundry/cc-api-v3-style-guide#example-4 i like the idea of a unique error code. ideally the CAPI team maintains public documentation of an error code dictionary https://github.com/cloudfoundry/cc-api-v3-style-guide#issues-with-v2-error-format the async proposal seems like a big improvement. On Wed, Sep 2, 2015 at 8:53 AM, James Bayer <jbayer(a)pivotal.io> wrote:
the collections example [1] does not actually include the required --
Thank you, James Bayer |
|
|
|
Zach Robinson
Thanks James, I've just corrected the three issues you've noted so far
|
|
|
|
Thanks for sharing this great spec.
toggle quoted message
Show quoted text
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 |
|
|
|
Dieu Cao <dcao@...>
Hi Guillaume,
toggle quoted message
Show quoted text
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. -Dieu On Mon, Sep 7, 2015 at 2:09 PM, Guillaume Berche <bercheg(a)gmail.com> wrote:
Thanks for sharing this great spec. |
|
|
|
Hi Dieu,
toggle quoted message
Show quoted text
Here are corresponding issues/comments submitted https://github.com/cloudfoundry/cc-api-v3-style-guide/issues/46 https://github.com/cloudfoundry/cc-api-v3-style-guide/issues/47 https://github.com/cloudfoundry/cc-api-v3-style-guide/issues/48 https://github.com/cloudfoundry/cc-api-v3-style-guide/issues/49 https://github.com/cloudfoundry/cc-api-v3-style-guide/issues/41#issuecomment-139050180 https://github.com/cloudfoundry/cc-api-v3-style-guide/issues/41#issuecomment-139051114 Guillaume. On Wed, Sep 9, 2015 at 10:39 AM, Dieu Cao <dcao(a)pivotal.io> wrote:
Hi Guillaume, |
|
|
|
Dieu Cao <dcao@...>
Thanks Guillaume!
toggle quoted message
Show quoted text
On Wed, Sep 9, 2015 at 2:33 PM, Guillaume Berche <bercheg(a)gmail.com> wrote:
Hi Dieu, |
|
|