Introduction to the Xray REST APIs

Xray provides a convenient and up-to-date self-descriptive API that can be used by various tools/frameworks to automate the creation of REST calls.

Usage

Xray REST API endpoints can be invoked in any of the standard ways to invoke a RESTful API. This section describes how to use the Xray REST API using cURL as an example.

Using and Configuring cURL

You can download cURL here. Learn how to use and configure cURL here.

Base URL

New API Version

From version 2.4, JFrog Xray is introducing a new REST API version. The different endpoints specified in this page will be upgraded gradually over progressive version upgrades, while maintaining backward compatibility to previous API versions. Where new endpoints are available, the API Version will be listed. In these cases, you should make sure to use corresponding Base URL as specified below. If the API version is not specified, it means the endpoint is part of the V1 REST API and you should use the V1 base URL.

The Platform REST URL is constructed of:

<JFrog URL>/<Service Context>/api/<API-Version>

For example:

# Using your JFrog URL 
http://myjfrog.acme.org/xray/api/v1

# Using your Artifactory server hostname and the Artifactory router port
http://ARTIFACTORY_SERVER_HOSTNAME:8082/xray/api/v1

Working with JFrog Platform Cloud

JFrog Platform Cloud offers the same extensive functionality and capabilities for automation as an on-prem installation, including authentication and the REST API endpoints.

As a Cloud service, the URL is different from an on-prem installation and the REST API endpoints can be reached at:

https://<Server Name>.jfrog.io/xray/

Authentication

Most REST API calls need to be authenticated using your user and password or using an access token. A few calls (such as SYSTEM calls) do not require authentication.

Example - Deleting a Watch

The example below demonstrates how to invoke the Delete Watch REST API with the following assumptions:

You are using cURL from the unix command line, and are presently working from the home (~) directory of the user 'myUser':
You wish to delete the watch called performance-watch.
You have configured a user in Xray named 'myUser', with password 'myP455w0rd!'.

To execute a call using basic authentication you would run:

curl -u myUser:myP455w0rd! -X DELETE http://SERVER_HOSTNAME:8082/xray/api/v2/watches/performance-watch

To execute a call using basic authentication using your username and API Key:User Profile

curl -uadmin:APIkey <Xray url>/xray/api/v2/watches

Component Identifiers

Several endpoints require the use of a component identifier which must be formatted, according to its package type, using the convention described in the following table:

Package Type	Identifier	Example
Maven	`gav://group:artifact:version`	`gav://ant:ant:1.6.5`
Docker and OCI	`docker://Namespace/name:tag`	`docker://jfrog/artifactory-oss:latest`
RPM	`rpm://os-version:package:epoch-version:version`	`rpm://7:rpm-python:7:4.11.3-43.el7`
Debian	`deb://vendor:dist:package:version`	`deb://ubuntu:trustee:acl:2.2.49-2`
NuGet	`nuget://module:version`	`nuget://log4net:9.0.1`
Generic file	`generic://sha256:<Checksum>/name`	`generic://sha256:244fd47e07d1004f0aed9c156aa09083c82bf8944eceb67c946ff7430510a77b/foo.jar`
NPM	`npm://package:version`	`npm://mocha:2.4.5`
Python	`pypi://package:version`	`pypi://raven:5.13.0`
Composer	`composer://package:version`	`composer://nunomaduro/collision:1.1`
Golang	`go://package:version`	`go://github.com/ethereum/go-ethereum:1.8.2`
Alpine	`alpine://branch:package:version`	`alpine://3.7:htop:2.0.2-r0`
Conan	`conan://vendor:name:version`	`conan://openssl:openssl:1.1.1g`
Conda	`conda://name:version`	`conda://matplotlib-base:3.5.3`
CRAN	`cran://name:version`	`cran://abess:0.4.7`
Cargo	`cargo://name:version`	`cargo://google_maps:3.0.1`
Hugging Face ML	`huggingfaceml://model_name:model_revision`	`huggingfaceml://mustrr/gpt2-elite:a1c740be581fa80e2d19961d15da96cb162fff85`
Terraform state	For Terraform state use the generic file identifier	`generic://sha256:147f9242fa6fa57cd7467ffd9450afc734860944e8c04e97b28a03c9c6328e24/state.latest.json`

In addition Build, Release Bundle, and Release Bundle V2 have dedicated identifiers:

Resource Type	Identifier	Example
Build Version	`build://[buildRepo]/bundleName:bundleVersion` `[buildRepo]` is optional It’s required if the build is in a Project scope.	`build://infra-build:2.3` `build://[core-project]/our-build:2`.3
Release Bundle Version	`releaseBundle://bundleName:bundleVersion`	`releaseBundle://MyRB:1.0`
Release Bundle V2 Version	`releaseBundleV2://[bundleRepoName]/bundleName:bundleVersion` `[bundleRepoName]` is required	`releaseBundleV2://[release-bundles-v2]/MyRBV2:1.0`

Resource Type

Identifier

Example

Build Version

build://[buildRepo]/bundleName:bundleVersion

[buildRepo] is optional

It’s required if the build is in a Project scope.

build://infra-build:2.3

build://[core-project]/our-build:2.3

Release Bundle Version

releaseBundle://bundleName:bundleVersion

releaseBundle://MyRB:1.0

Release Bundle V2 Version

releaseBundleV2://[bundleRepoName]/bundleName:bundleVersion

[bundleRepoName] is required

releaseBundleV2://[release-bundles-v2]/MyRBV2:1.0

Deprecated APIs from Artifactory 7.x

To fully support the integration of JFrog Xray into the JFrog Platform, a set of Xray API commands have been deprecated. For a full list of deprecated commands, see deprecated REST APIs.