Entwickler

Datenformate der Public API

Wie die Costfluent Public API Geldbeträge, Datumsangaben, Währungen und IDs schreibt und wie ein Schreibzugriff an die gelesene Version gebunden wird.

Das OpenAPI-Dokument legt das Format jedes Felds fest. Diese Seite erklärt die, mit denen eine Integration sorgfältig umgehen muss.

Geldbeträge

Jeder Geldbetrag ist ein Dezimal-String, nie eine JSON-Zahl, damit kein Client binäre Gleitkommazahlen summiert, die abdriften:


Code
{ "amount": "1250.50000000", "currency": "EUR" }

Antworten schreiben jeden Betrag mit genau acht Nachkommastellen, einem Punkt und ohne Exponent.
Anfragen senden einen Betrag ebenso, mit bis zu acht Nachkommastellen: "1250.5" und "1250.50000000" sind derselbe Betrag. Eine JSON-Zahl, ein Exponent oder ein Tausendertrennzeichen wird mit 400 abgelehnt.
Ein Budgetbetrag wird auf den Cent genau gespeichert; ein Budgetbetrag mit mehr als zwei Nachkommastellen wird daher abgelehnt statt gerundet.
Vergleiche Beträge nach Wert, nicht als Text: "49" und "49.00000000" sind gleich.
Prozentwerte, Verhältnisse wie die Zuordnungsabdeckung, Wechselkurse und Verbrauchsmengen bleiben JSON-Zahlen.
Der thresholdValue einer Kostenwarnung ist ein Dezimal-String, ob er ein Betrag oder ein Prozentwert ist, wie ihr thresholdType sagt.

Datumsangaben und Monate

Ein Datum ist YYYY-MM-DD, etwa startDate, endDate und der chargePeriodStart einer benutzerdefinierten Integration. Ein Abrechnungszeitraum ist ein Tag; eine Uhrzeit wird daher abgelehnt.
Ein Prognosemonat ist YYYY-MM.
Ein Zeitstempel wie createdAt ist ein Datum mit Uhrzeit nach ISO 8601.

Währungen

Eine Währung ist ein ISO-4217-Code aus drei Großbuchstaben, etwa EUR oder GBP.

IDs

Jedes Costfluent-Objekt wird über eine ID mit Präfix angesprochen, etwa wsp_ für einen Workspace, bud_ für ein Budget, crp_ für einen Kostenbericht, seg_ für ein Segment und prv_ für eine Integration. Das Präfix sagt, was die ID bezeichnet, und die API lehnt eine ID der falschen Art ab. Behandle den Rest als undurchsichtig.

Ein Kosten-Batch an eine benutzerdefinierte Integration antwortet mit einer batchId, die mit cbt_ beginnt: eine Quittung für diesen Batch, kein Upload, den du zurücklesen kannst.

Bedingte Änderungen

Das Lesen eines Budgets antwortet mit einem ETag-Header, der Version des zurückgegebenen Budgets. Sende ihn als If-Match mit dem PUT zurück, das das Budget ändert:

Code
curl --request PUT https://api.costfluent.com/v1/budgets/$BUDGET_ID \
  --header "Authorization: Bearer $COSTFLUENT_API_TOKEN" \
  --header "If-Match: \"774\"" \
  --header "Content-Type: application/json" \
  --data '{"amount": "15000"}'

Hat jemand das Budget nach deinem Lesen geändert, wird das PUT mit 412 und precondition_failed abgelehnt, und nichts ändert sich: Lies es erneut und entscheide dann. Ohne If-Match gewinnt der letzte Schreibzugriff.

Wie es sich verhält

Anlegen und Ändern eines Budgets antworten ebenfalls mit seinem neuen ETag.
If-Match: * wendet die Änderung unabhängig von der Version an.
Der Terraform-Provider sendet das ETag seines letzten Lesens; eine Änderung in Costfluent zwischen einem Plan und seinem Apply stoppt das Apply daher, statt überschrieben zu werden.

Verwandte Seiten

Rate Limits der Public API Webhook-Benachrichtigungen

Geldbeträge

Jeder Geldbetrag ist ein Dezimal-String, nie eine JSON-Zahl, damit kein Client binäre Gleitkommazahlen summiert, die abdriften:

Code

{ "amount": "1250.50000000", "currency": "EUR" }

Antworten schreiben jeden Betrag mit genau acht Nachkommastellen, einem Punkt und ohne Exponent.

Anfragen senden einen Betrag ebenso, mit bis zu acht Nachkommastellen: "1250.5" und "1250.50000000" sind derselbe Betrag. Eine JSON-Zahl, ein Exponent oder ein Tausendertrennzeichen wird mit 400 abgelehnt.

Ein Budgetbetrag wird auf den Cent genau gespeichert; ein Budgetbetrag mit mehr als zwei Nachkommastellen wird daher abgelehnt statt gerundet.

Vergleiche Beträge nach Wert, nicht als Text: "49" und "49.00000000" sind gleich.

Prozentwerte, Verhältnisse wie die Zuordnungsabdeckung, Wechselkurse und Verbrauchsmengen bleiben JSON-Zahlen.

Der thresholdValue einer Kostenwarnung ist ein Dezimal-String, ob er ein Betrag oder ein Prozentwert ist, wie ihr thresholdType sagt.

IDs

Ein Kosten-Batch an eine benutzerdefinierte Integration antwortet mit einer batchId, die mit cbt_ beginnt: eine Quittung für diesen Batch, kein Upload, den du zurücklesen kannst.

Bedingte Änderungen

Das Lesen eines Budgets antwortet mit einem ETag-Header, der Version des zurückgegebenen Budgets. Sende ihn als If-Match mit dem PUT zurück, das das Budget ändert:

Code

curl --request PUT https://api.costfluent.com/v1/budgets/$BUDGET_ID \
  --header "Authorization: Bearer $COSTFLUENT_API_TOKEN" \
  --header "If-Match: \"774\"" \
  --header "Content-Type: application/json" \
  --data '{"amount": "15000"}'

Wie es sich verhält

Anlegen und Ändern eines Budgets antworten ebenfalls mit seinem neuen ETag.

If-Match: * wendet die Änderung unabhängig von der Version an.

Der Terraform-Provider sendet das ETag seines letzten Lesens; eine Änderung in Costfluent zwischen einem Plan und seinem Apply stoppt das Apply daher, statt überschrieben zu werden.