Updating objects with the Public API
How a Costfluent Public API update changes only the fields it names, empties a field with its clear flag, and replaces a list whole.
Every update in the Public API, a PUT or a PATCH, changes the object in place: it keeps its ID and everything that hangs off it. A field you leave out keeps its value, so a client sends only what changed.
Change, keep or empty a field
| You send | The field |
|---|---|
| A value | takes the value |
Nothing, or null | keeps its value |
Its clear flag, such as "clearDescription": true | is emptied |
| A value and its clear flag together | is not changed: the request is refused with 400 and nothing changes |
A field that has no clear flag cannot be emptied by an update.
A list, such as appIds on a budget or a cost alert, is replaced whole: send every item it should hold. An empty list removes them all.
To return a budget from a saved cost report to the whole workspace:
Code
Clear flags
| Object | Clear flags |
|---|---|
Budget, PUT /v1/budgets/{budgetId} | clearSegment, clearCostReport |
Cost alert, PUT /v1/cost-alerts/{alertId} | clearComparisonPeriod, clearMinimumAmount, clearFilter |
Cost report, PUT /v1/cost-reports/{costReportId} | clearFolder, clearFilter, clearStartDate, clearEndDate |
Folder, PUT /v1/folders/{folderId} | clearParent |
Integration, PUT /v1/providers/{providerId} | clearDescription, clearSettings |
Virtual tag, PATCH /v1/virtual-tags/{virtualTagId} | clearDescription, clearDefaultValue |
How it behaves
- An update answers
200with the object as stored, as reading it would, and a deletion answers204with no body. Setting a team member or a team's workspace access answers204, because it links two objects rather than holding one. - Renaming an integration with
namekeeps its ID, its credentials and the costs it has already collected. - A budget measures a segment, a saved cost report or the whole workspace. Naming
segmentIdorcostReportIdmoves it there, and its clear flag returns it to the whole workspace. - A segment always has an owner. Naming
teamIdreplaces its team label, and namingteamLabelreplaces its team. - A cost report with a custom interval needs both dates, so clearing either is refused until the report uses another interval.
- An integration's
settingsare replaced whole when you send at least one; an empty map keeps them. - The
saved-filteroperations of a dashboard and a folder are the one exception: there,savedFilterId: nulldetaches the saved filter. - An allocation rule's update names its
name,filterandsegmentIdevery time, and a team, a team member and a team's workspace access are updated whole. - A workspace's tag policy,
PUT /v1/workspaces/{workspaceId}/tag-policy, is replaced whole:rulesis required, and an empty list clears the policy.
Where reading an object answers with an ETag, send it back as If-Match, and the update is refused when someone changed the object since you read it. See Data formats.