Introduction to the Xray REST APIs

Xray REST APIs
Products
JFrog Xray
Content Type
REST API
ft:sourceType
Paligo

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

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.