Zum Inhalt springen
Craftifact

Artefakt-Suche API

Referenz zum Auflösen vorhandener Paket-Artefakt-IDs über repositorybezogene Koordinaten oder exakte Datei-Attribute.

GET /api/artifacts/search/

Zweck

  • eine vorhandene artifact_id vor nachfolgenden API-Aufrufen auflösen
  • Lookups deterministisch halten, indem du ein Repository mit genau einem Lookup-Modus kombinierst
  • nur Artefakte zurückgeben, die für den authentifizierten Nutzer sichtbar sind

Request

Query-Parameter

Sende immer repository.

Dann wählst du genau einen Lookup-Modus:

Paketkoordinaten

  • Maven: format=maven mit name, optional group_id, optional version
  • Python, npm, Go: format mit name, optional version

Das ist passend, wenn du die Paketkoordinaten kennst und direkt die passende Artefakt-ID auflösen willst.

Pfad oder Dateiname

  • path
  • filename

Nutze einen der beiden Werte oder beide zusammen, wenn deine Automation den gespeicherten Repository-Pfad und Dateinamen kennt.

Digest

  • digest

Das ist passend, wenn du den gespeicherten Checksum- oder Content-Digest des Paketartefakts bereits kennst.

Validierungsregeln:

  • repository ist erforderlich
  • group_id funktioniert nur mit format=maven
  • version funktioniert nur zusammen mit name
  • kombiniere repository mit genau einem Lookup-Modus
  • limit ist standardmäßig 20 und darf höchstens 100 sein
  • offset ist standardmäßig 0
Name Erforderlich Typ
repository Erforderlich string
format Optional string · enum: maven, python, npm, go
group_id Optional string
name Optional string
version Optional string
path Optional string
filename Optional string
digest Optional string
limit Optional integer
offset Optional integer

Responses

Typische Statuscodes:

  • 200 OK: passende sichtbare Artefakte wurden aufgelöst, oder die Ergebnismenge ist leer.
  • 400 Bad Request: dem Query fehlt repository, er mischt Lookup-Modi oder nutzt nicht unterstützte Parameter.
  • 401 Unauthorized: es wurden keine gültigen programmatischen Zugangsdaten übermittelt.
200

OK

Resolved artifact matches visible to the authenticated caller. When no visible artifact matches the lookup, the response still succeeds with an empty results array.
results Erforderlich

array

Visible artifacts that matched the requested lookup mode.
total Erforderlich

integer

Total number of matches before pagination.
limit Erforderlich

integer

Effective result limit applied to the response.
offset Erforderlich

integer

Effective result offset applied to the response.
200 Beispiel-JSON 
{
  "results": [
    {
      "artifact_id": "4fd75091-2d3a-48b7-9e35-85a5edfa1d92",
      "repository": "libs-release",
      "format": "maven",
      "name": "demo",
      "group_id": "com.example",
      "version": "1.2.3",
      "path": "com/example/demo/1.2.3",
      "filename": "demo-1.2.3.jar"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
400

Bad Request

Bad request. Typical causes include:

  • repository is missing.
  • format is unsupported.
  • group_id was provided outside Maven mode.
  • no lookup mode was selected.
  • multiple lookup modes were combined in one request.
  • limit or offset is invalid.
error Erforderlich

string

Human-readable error message for the rejected upload.
400 Beispiel-JSON 
{
  "error": "combine repository with exactly one lookup mode"
}
401

Unauthorized

Authentication failed or no programmatic credentials were provided.
error Erforderlich

string

Human-readable error message for the rejected upload.
401 Beispiel-JSON 
{
  "error": "authentication required"
}

Beispiele

curl: über Maven-Koordinaten auflösen 
curl \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  "https://packages.example.com/api/artifacts/search/?repository=libs-release&format=maven&group_id=com.example&name=demo&version=1.2.3"
curl: über Pfad auflösen 
curl \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  "https://packages.example.com/api/artifacts/search/?repository=libs-release&path=com/example/demo/1.2.3&filename=demo-1.2.3.jar"

Verwandte Seiten