V3 Capi documentation does not list return structure

[mvadu]

Issue

V3 Capi documentation does not list return structure. It only lists query parameters and permitted roles. It does not say what to expect from the API (aka service contract).

Context

Old V2 Capi documentation (e.g. https://apidocs.cloudfoundry.org/15.3.0/services/list_all_services.html) lists actual response body, and expected members. That helps to design a consuming class (a dotnet class in my case). But V3 documentation (e.g. http://v3-apidocs.cloudfoundry.org/version/release-candidate/#list-droplets-for-an-app) just shows who can consume the API in terms of permitted roles and query parameters. This is equivalent to consumer side of service contract.

Without the provider side of service contract its hard to program the consumer. Can Pivotal/CloudFoundry add return data structure details?

[cf-gitbot]

We have created an issue in Pivotal Tracker to manage this:

https://www.pivotaltracker.com/story/show/176808524

The labels on this github issue will be updated when the story is started.

[sethboyles]

@mvadu For the expected format of returned objects you can look at the individual object documentation e.g: http://v3-apidocs.cloudfoundry.org/version/release-candidate/#the-droplet-object

Is there a reason this is not sufficient for your purposes?

[mvadu]

@sethboyles It is probably, but the said object is not linked from page for List droplets for an app page. Probably having a simple header Returns the-droplet-object

Reason is if you look at same droplet object definition, it mentions detected buildpack, but detected buildpack is different from the-buildpack-object.

Making the return objects types cross linked in the API reference makes life easier when you have to write a consumer code and make sure the deserialization works.