GraphQL

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: