Skip to content
This repository was archived by the owner on Jun 2, 2021. It is now read-only.

Commit f75525c

Browse files
committed
v3 docs: Add "Resource Summaries" section to upgrade guide
This is just the first pass at this section. I think we can add more. The goal is to help clients understand why we got rid of most summary endpoints and how they can achieve similar goals in V3. Authored-by: Reid Mitchell <rmitchell@pivotal.io>
1 parent 6d570b5 commit f75525c

2 files changed

Lines changed: 22 additions & 0 deletions

File tree

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
### Resource Summaries
2+
3+
V2 provided several endpoints that returned rolled-up summaries (e.g.
4+
`/v2/spaces/:guid/summary` for a space summary, or
5+
`/v2/organizations/:guid/summary` for an organization summary). These endpoints
6+
have been largely removed from V3 because they were expensive for Cloud
7+
Controller to compute and because they often returned more information than
8+
clients actually needed. They were convenient, so it was easy for clients to
9+
rely on them even when they only needed a few pieces of information.
10+
11+
In V3, to enable better API performance overall, these usage patterns are
12+
deliberately disallowed. Instead, clients are encouraged to think more carefully
13+
about which information they really need and to fetch that information with
14+
multiple API calls and/or by making use of the [`include`
15+
parameter](#including-associated-resources) on certain endpoints.
16+
17+
#### Usage summary endpoints
18+
19+
There are still a couple of endpoints in V3 that provide a basic summary of
20+
instance and memory usage. See the [org summary](#get-usage-summary) and
21+
[platform summary](#get-platform-usage-summary) endpoints.

docs/v3/source/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -372,6 +372,7 @@ includes:
372372
- upgrade_guide/conceptual_changes/errors
373373
- upgrade_guide/conceptual_changes/filtering
374374
- upgrade_guide/conceptual_changes/including_associated_resources
375+
- upgrade_guide/conceptual_changes/resource_summaries
375376
- upgrade_guide/new_concepts/header
376377
- upgrade_guide/new_concepts/actions
377378
- upgrade_guide/new_concepts/links

0 commit comments

Comments
 (0)