API-Referenz.

Eine HTTPS-API, aufgerufen mit curl aus jeder Pipeline. Nichts zu installieren und nichts zu betreiben: Die CI-Anbindung ist diese API und ein Beispiel zum Kopieren.

BitHive Reporting Desk API · 0.11.0

Authentifizierung

Jede Anfrage trägt ein API-Token als Bearer-Token: „Authorization: Bearer <token>“. Token werden in der Anwendung erstellt, tragen Scopes, können auf ein Produkt begrenzt werden und laufen ab. Ein unbekanntes, abgelaufenes oder widerrufenes Token wird mit 401 und einem Problemdokument beantwortet.

Scopes

Ein Token trägt die Scopes, die ihm gegeben wurden, und sonst keine. Ein Endpunkt, der einen fehlenden Scope braucht, antwortet mit 403; welcher Scope nötig ist, steht unten bei jedem Endpunkt.

Scope	Erlaubt
`products:read`	Die Produkte des Kontos lesen.
`sboms:read`	Hochgeladene Stücklisten, ihre Komponenten und das gespeicherte Dokument lesen.
`sboms:write`	Stücklisten hochladen, ihre Produktversionen benennen und auf den Markt bringen oder vom Markt nehmen.
`findings:read`	Die Befunde eines Produkts und seine Abdeckung lesen.
`sboms:upload`	Stücklisten hochladen und sonst nichts; der Upload akzeptiert auch sboms:write.
`cases:read`	Die CRA-Fälle mit ihren Fristen und dem Stand der Meldung jeder Stufe lesen.
`records:read`	Die Vorfallsakten mit ihren Pflichten und Fristen lesen, so wie die Person, die das Token erstellt hat, sie sieht.
`records:write`	Vorfallsakten anlegen und Meldungen als eingereicht erfassen; nur für Konten in der Beta.
`findings:decide`	VEX-Aussagen zu den Befunden eines Produkts festhalten, wie es der Ersteller des Tokens darf.

Anfragegrenzen

Zwei Grenzen, beide pro Stunde gezählt. Ein Token darf 600 Anfragen in einer Stunde stellen; eine Adresse, die nicht funktionierende Token vorlegt, wird nach 20 Fehlversuchen abgewiesen. Über einer der beiden Grenzen lautet die Antwort 429, mit einem Retry-After-Header, der die Länge des Fensters nennt.

Fehler

Diese Antworten kann jeder Endpunkt geben; deshalb stehen sie einmal hier und nicht bei jedem einzelnen. Der Körper ist ein Problemdokument (RFC 9457), der Content-Type application/problem+json. Bei den Endpunkten stehen nur die Antworten, die für sie besonders sind.

Status	Bedeutung
`401`	Das API-Token fehlt, ist unbekannt, abgelaufen oder widerrufen.
`403`	Dem API-Token fehlt die erforderliche Berechtigung, oder, bei einem Schreibvorgang, das Konto ist gesperrt, weil eine Zahlung offen ist oder sein Abonnement beendet ist. Lesen ist in beiden Fällen weiter möglich; das Feld detail sagt, welcher Fall zutrifft.
`404`	Die Ressource existiert nicht, oder das Token darf sie nicht sehen.
`405`	Die Ressource unterstützt diese Methode nicht.
`413`	Das Dokument ist größer als 10 MiB.
`429`	Der Aufrufer hat eine der beiden Grenzen überschritten: Anfragen für dieses Token oder fehlgeschlagene Authentifizierungen von dieser Adresse. Retry-After gibt an, wie lange das Zeitfenster dauert.

Beispiel

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The API token is unknown, expired or revoked."
}

Server

https://app.bithive-it.com Produktion

Produkte

GET Produkte des Kontos auflisten /v1/products
GET Ein Produkt lesen /v1/products/{productId}

Stücklisten

GET Uploads eines Produkts auflisten /v1/products/{productId}/sboms
POST Stückliste für ein Produkt hochladen /v1/products/{productId}/sboms
GET Einen Upload lesen /v1/sboms/{sbomId}
PATCH Produktversion benennen, auf den Markt bringen oder vom Markt nehmen /v1/sboms/{sbomId}
GET Komponentenverzeichnis eines Uploads lesen /v1/sboms/{sbomId}/components
GET Dokument so herunterladen, wie es hochgeladen wurde /v1/sboms/{sbomId}/document

Befunde und Abdeckung

GET Befunde eines Produkts auflisten /v1/products/{productId}/findings
POST Eine VEX-Aussage zu den Befunden eines Produkts festhalten /v1/products/{productId}/decisions
GET Die Aussagen zu einer Produktversion und einer Schwachstelle lesen /v1/products/{productId}/decisions/history
GET Das VEX-Dokument eines Produkts herunterladen /v1/products/{productId}/vex
GET Lesen, wie viel von einem Produkt geprüft werden kann /v1/products/{productId}/coverage

Cases

GET CRA-Fälle auflisten /v1/cases
GET Einen CRA-Fall mit seinen Fristen und dem Stand seiner Meldungen lesen /v1/cases/{caseId}

Vorfallsakten

GET Vorfallsakten auflisten /v1/records
POST Vorfallsakte anlegen /v1/records
GET Eine Vorfallsakte mit ihren Pflichten und Fristen lesen /v1/records/{recordId}
POST Meldung einer Stufe als eingereicht erfassen /v1/records/{recordId}/submissions
POST Vertrag archivieren /v1/contracts/{contractId}/archive
POST Archivierten Vertrag wiederherstellen /v1/contracts/{contractId}/restore

Was zurückkommt

Der Vertrag selbst. Diese Seite entsteht aus dem OpenAPI-Dokument des Dienstes. Es ist als Datei veröffentlicht, damit ein Client-Generator denselben Vertrag lesen kann, den diese Seite beschreibt. openapi.yaml herunterladen

Doku

14 Tage kostenlos testen