GraphQL

JFrog REST APIs

ft:sourceType
Paligo

Overview

GraphQL is a query language that enables you to query your APIs and fetch specific data that you need. Using one endpoint, you can query just the data you want to retrieve and receive a JSON response containing that specific data. To learn more about GraphQL, the query language, type system, how the GraphQL service works, as well as best practices for using GraphQL see GraphQL documentation.

Using GraphQL to Query Metadata

Authentication

Using GraphQL to query metadata provides a simple way to fetch packages data stored in the metadata microservice. Since GraphQL enables you to query objects in a hierarchical structure, and allows you to choose which fields to include in a response, it will be simpler to find the exact data you are looking for.

To use the metadata server GraphQL, you will need a scoped token for Artifactory.

cURL Example

curl -H "Authorization: Bearer <Your Token>" -XPOST http://<server:port>/metadata/api/v1/query -d '{"query":"..." }'

GraphiQL

JFrog offers a version of a simple GraphiQL, a UI tool for your GraphQL queries. You can use the GraphiQL to learn about the GraphQL metadata schema and as a playground to test your queries. To access it, <your server url>/metadata/api/v1/query/graphiql.

Building a Metadata GraphQL Query

In this section, you will learn about the structure of a query, how to construct a query, and the available Metadata queries.

Pagination

The Metadata GraphQL implementation utilizies GraphQL's pagination convention using the GraphQL connection model. This means that every entity queried is embedded within a wrapper containing the pagination information. To learn more, see GraphQL Pagination.

GraphQL query enables you to sort and order your queries by using a set of predefined arguments. Available sort arguments are First (limit), After (Offset) and OrderBy.

For example, for Package pagination you can use: (first:5 after:$PackageCursor). The Package cursor is retrieved from the last Package queried. Additionally, you can get the last Package cursor and know if there are additional Packages to query by adding the pageInfo to your query.

Pagination Example

query
{
  packages (
    # filter argument
    filter: {name: "*" },
    first: 5,
    after: "UGFja2FnZTo1"
  )
  {
   pageInfo 
    { 
    hasNextPage  
    endCursor
  }
    # Connection Model
    edges {
      cursor
      node {
        #Object fields to be returned by the query  
        name
        packageType
        description
        }
      }
    } 
}
Available Queries

The following are the queries available for the Metadata GraphQL.

Packages
packages(
filter: PackageFilter!
first: Int
after: ID
orderBy: PackageOrder
): PackageConnection!
Versions
versions( 
filter: VersionFilter! 
first: Int 
after: ID 
orderBy: VersionOrder 
): VersionConnection!
Files
files( 
filter: FileFilter! 
first: Int 
after: ID 
orderBy: FileOrder 
): FileConnection!
Filter Types

The following describes the available filter names you can use to construct a filter for each of the query types.

PackageFilter!

Filter Name

Type

Description

Example

name

Case sensitive pattern

Match package names against a pattern.

name: "arti*"

packageTypeIn

[PackageType!]

Match packages of one of the given types.

packageTypeIn: [BOWER, COCOAPODS]

createdMin

Time

Match packages with a "created date" equal or after provided date.

createdMin: "2019-12-25T00:00:01.000Z"

createdMax

Time

Match packages with a "created date" equal or before provided date.

createdMax: "2019-12-25T00:00:01.000Z"

modifiedMin

Time

Match packages with a "modified date" equal or after provided date.

modifiedMin: "2019-12-25T00:00:01.000Z"

modifiedMax

Time

Match packages with a "modified date" equal or before provided date.

modifiedMax: "2019-12-25T00:00:01.000Z"

latestVersion

Case sensitive pattern

Match packages with the latest version matching the provided pattern.

latestVersion: "*ersion*"

versionCountMin

Int

Match packages with at least a certain amount of versions.

versionCountMin: 1

versionCountMax

Int

Match packages with at most a certain amount of versions.

versionCountMax: 1

VersionFilter!

Filter Name

Type

Description

Example

name

Case sensitive pattern

Match version names against a pattern

name: "*1.1*"

createdMin

Time

Match versions with a "created date" equal or after provided date.

createdMin: "2019-12-25T00:00:01.000Z"

createdMax

Time

Match versions with a "created date" equal or before provided date.

createdMax: "2019-12-25T00:00:01.000Z"

sizeMin

String

Match versions with size greater than or equal to provided size.

sizeMin: "100"

sizeMax

String

Match versions with size less than or equal to provided size.

sizeMax: "100"

licenses

List Filter

Match versions with licenses.

licenses: {patterns: ["*gpl", "apache"]}

tags

List Filter

Match versions with tags.

tags: {patterns: ["tag*","?tag*"]}

properties

[NameValuePattern!]

Match versions with a specific set of properties.

properties: [{name:"*key1", value:"*value1"}, {name:"*key2", value:"*value2"}]

vulnerabilities

[VulnerabilitiesFilter!]

Match versions with vulnerabilities.

vulnerabilities: [{level: LOW, countMin: 3}, {level: HIGH, countMin: 5}]

FileFilter!

Filter Name

Type

Description

Example

name

Case sensitive pattern

Match file names

name: "*1.1*"

sizeMin

String

Match files with size greater than or equal to provided size.

sizeMin: "100"

sizeMax

String

Match files with size less than or equal to provided size

sizeMax: "100"

md5

Case sensitive pattern

Match MD5 hashes against a pattern

md5: "5eb63bbbe01eeed093cb22bb8f5*"

sha1

Case sensitive pattern

Match SHA-1 hashes against a pattern

sha1: "2aae6c35c94fcfb415dbe95f408b9ce91*"

sha256

Case sensitive pattern

Match SHA-256 hashes against a pattern

sha256: "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9*"

Entities and Fields
Packages

Field

Type

name

String!

packageType

String!

created

Time!

modified

Time!

versionsCount

Int!

vcsUrl

String!

issuesUrl

String!

description

String!

latestVersion

String!

licenses

[License!]

properties

[Property!]

qualifiers

[Qualifier!]

versions

[Version]

sources

[Source!]

tags

[String!]

stats

PackageStats

vulnerabilities

Vulnerabilities

Licenses

Field

Type

name

String!

source

String!

description

String!

modified

Time!

url

String!

Properties

Field

Type

name

String!

value

String!

Qualifiers

Field

Type

name

String!

value

String!

Versions

Field

Type

name

String!

size

String!

created

Time!

modified

Time!

license

Entity

files

Entity

repos

VersionRepository

tags

Entity

stats

VersionsStats

qualifiers

Entity

properties

Entity

contributors

VersionContributors

vulnerabilities

VersionVulnerabilties

Sources

Field

Type

name

String!

url

String!

modified

Time!

PackageStats

Field

Type

downloads

Int!

followers

Int!

VersionVulnerabilities

Field

Type

high

Int!

medium

Int!

low

Int!

info

Int!

unknown

Int!

skipped

Int!

Files

Field

Type

name

String!

md5

String!

sha1

String!

sha256

String!

lead

Bolean

length

String!

arch

String!

dist

String!

compiler

String!

compilerVersion

String!

mimeType

String!

qualifiers

Entity

VersionRepository

Field

Type

name

String!

url

String!

type

String!

leadFilePath

String!

VersionStats

Field

Type

downloadCount

Int!

VersionContributor

Field

Type

name

String!

type

String!

email

String!

url

String!

Query Examples
Example 1 - Package by name and type

Query

# Query package name and description, filtered by name pattern, ordered by name descending
query {
    packages(
        filter: {
            name: "*ello*",
            packageTypeIn: [NPM, DOCKER]
        },
        first: 3,
        orderBy: {
            field: NAME,
            direction: DESC
        }
    ) {
        edges {
            node {
                name
                description 
            }
        }
    }
}

Sample Result

{
  "data": {
    "packages": {
      "edges": [
        {
          "node": {
            "name": "p2Hello",
            "description": "Sample Package 2"
          }
        },
        {
          "node": {
            "name": "p1Hello",
            "description": "Sample Package 1"
          }
        },
        {
          "node": {
            "name": "library/hello-world",
            "description": null
          }
        }
      ]
    }
  }
}
Example 2 - Package with its Versions and Licenses by creation date

Query

# Query Package name description and creation date, with its version names and sizes, and associated licenses name and source for each version. 
# filtered by package creation date, limited to first 3 results.
query {
    packages(
        filter: {
            createdMin: "2020-01-01T01:59:00.000Z"
        },
        first: 3
      ) 
    {
        edges {
            node {
                name
                description 
                created
                versions{
                    name
                    size
                    licenses{
                        name
                        source
                    }
                }
            }
        }
    }
}

Sample Result

{
  "data": {
    "packages": {
      "edges": [
        {
          "node": {
            "name": "sample_rpm-1",
            "description": "Sample RPM Package for data generation",
            "created": "2020-01-05T09:53:21.588Z",
            "versions": [
              {
                "name": "0:2.0.0-2.0.0",
                "size": "2080",
                "licenses": [
                  {
                    "name": "MIT",
                    "source": "Local File"
                  }
                ]
              },
              {
                "name": "0:8.0.0-8.0.0",
                "size": "2080",
                "licenses": [
                  {
                    "name": "MIT",
                    "source": "Local File"
                  }
                ]
              }
            ]
          }
        },
        {
          "node": {
            "name": "example package 7",
            "description": null,
            "created": "2020-01-09T18:02:48.604Z",
            "versions": [
              {
                "name": "0.4.6",
                "size": "",
                "licenses": [
                  {
                    "name": "Apache-2.0",
                    "source": "Local File"
                  }
                ]
              }
            ]
          }
        },
        {
          "node": {
            "name": "another example",
            "description": "a nice package for web apps",
            "created": "2020-01-05T17:43:13.979Z",
            "versions": [
              {
                "name": "1.2.32",
                "size": "",
                "licenses": [
                  {
                    "name": "MIT",
                    "source": "Local File"
                  }
                ]
              },
              {
                "name": "1.7.9",
                "size": "623646",
                "licenses": [
                  {
                    "name": "MIT",
                    "source": "Local File"
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  }
}

Watch the Tutorial

Here is a video demonstrating how to use the GraphQL playground to retrieve packages metadata: