JFrog OneModel GraphQL

OneModel aligns domain models and terminology across the JFrog Platform, providing a unified entry point for querying cross-platform information. Starting from Artifactory version 7.104.1, you can use JFrog OneModel GraphQL queries to get information from multiple JFrog products and services through a single endpoint. Additionally, GraphQL queries enable you to query only the data you need and remove unnecessary fields.

For example, to get information about Release Bundles and evidence associated with them using OneModel, you can use a single query and receive connected information about release bundles and their respective evidence data, instead of using two separate queries and matching the information using regular REST API requests.

Explore OneModel Services

Select a service to view common use cases, key entities, and practical query examples:

Evidence GraphQL: Query security and compliance evidence attached to your artifacts. For more information, see Evidence GraphQL.
Stores Packages GraphQL: Search and retrieve rich metadata for stored packages and versions. For more information, see Stored Packages GraphQL.
Release Lifecycle Management GraphQL: Track artifacts and builds through their release stages. For more information, see Release Lifecycle Management GraphQL.

Key Benefits of JFrog OneModel GraphQL

Standardize terminology: Use a common language across the JFrog Platform, eliminating inconsistent data models across products.
Query a single endpoint: Access all domains (packages, security evidence, release lifecycles) through one federated GraphQL endpoint instead of managing multiple REST APIs.
Fetch only what you need: Request exact data fields to eliminate massive payloads, speed up queries, and reduce bandwidth.
Retrieve connected insights: Fetch related information across different domains in a single query, such as pulling a Release Bundle and its security evidence simultaneously.
Access real-time documentation: Rely on a self-documenting schema via the GraphQL Playground, eliminating drift between written specifications and actual implementations.
Ensure API stability: Rely on strict "model-as-code" governance that significantly reduces unexpected breaking changes in your integrations.

Explore Schema With GraphQL Playground

The best way to understand and interact with the OneModel API is by using the built-in GraphQL Playground.

The Playground is an interactive, in-browser graphical IDE that lets you explore the entire OneModel schema, write queries with auto-completion, and view responses in real time. Because the OneModel schema is self-documenting, the Playground is always your most accurate and up-to-date resource for field-level details, required arguments, and data types.

To use GraphQL Playground:

Log in to the JFrog Platform UI
In the Platform module, navigate to Integrations > GraphQL Playground
Build your query on the left pane: Use keyboard shortcuts to trigger auto-complete for fields and arguments.
1. Open the right-side tabs to browse all available queries, mutations, and types across all services.
Click the play ( ▶️ ) icon to execute your query and view the JSON response in the right pane.

Use OneModel GraphQL

Using OneModel, you can access all supported domains using the following unified endpoint:

POST <your-jfrog-domain>/onemodel/api/v1/graphql

JFrog OneModel GraphQL currently supports the POST with JSON format. For more information, see Request Format and Response Format.

To use the OneModel endpoint, execute your query using cURL or an API client application such as Postman.

Usage Examples

Query Example

Use the following query to get the first five evidences from the repository, example-repo-local:

query {
  evidence {
    searchEvidence(first: 5, where: {
      hasSubjectWith: {
        repositoryKey: "example-repo-local",
        path: "path/to",
        name: "file.ext"}}) {
      edges {
        node {
          predicateSlug
          predicateType
          predicate
          verified
          downloadPath
          subject {
            path
            name
          }
        }
      }
    }
  }
}

cURL Example

Use the following cURL command to execute an API request:

curl --location -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
https://<your-jfrog-domain>/onemodel/api/v1/graphql \
-d '{"query":"query { evidence { searchEvidence( first: 5, where: { hasSubjectWith: { repositoryKey: \"example-repo-local\" } } ) { totalCount } } }"}'

Authenticate API Requests

Using OneModel GraphQL requires a JFrog access bearer token, scoped to the content you are querying. For more information about token scopes, see Create Scoped Token.

When using OneModel GraphQL, make sure your token audience is configured as a wildcard (*@*). For more information, see Create Token.

OneModel GraphQL only returns data that you have permission to view. If you do not have the appropriate permissions for the data, OneModel GraphQL returns an error. For example, to query evidence information for one project in your instance, you must have read permissions for evidence on this project.

Common Patterns And Conventions

This section explains the patterns and conventions applied across all OneModel domains.

Best Practices

To get the best performance and reliable results from the OneModel API:

Ask only for what you need: Request only the fields you need to minimize response size and improve query performance.
Use pagination for large result sets: Always specify first and use the after cursor for subsequent pages to handle large datasets efficiently.
Filter early: Apply filtering criteria directly in the query instead of fetching large datasets and filtering them in the application layer.
Use variables for dynamic queries: Define variables for dynamic values to make queries cleaner and reusable.

Namespaces And Queries

Each domain in the JFrog Platform model is mapped to a namespace, which is represented by a field in the GraphQL root query. The namespace field contains the actual queries.

Queries are named according to the following convention:

search... for queries that return a list of items.
get... for queries that return a single item, or a ‘not found’ error if the item is not found.

Search queries usually accept the following arguments to filter and order the results:

where: A filter object that contains the filtering criteria.
orderBy: A filter object that defines the result ordering.

The where and orderBy arguments are not supported for all queries. Check the specific query before using these arguments.

Pagination

Search queries provide paginated results to allow the handling of very large result sets. Pagination is cursor-based and implemented according to the widely adopted Relay style.

To iterate over pages, use the following query arguments:

first: The number of items to include in the page.
after: The cursor value of the item after which to fetch the page.

Paginated queries also support backward pagination using the following arguments:

last: The number of items to include in the page.
before: The cursor value of the first item in the next page.

Pagination query arguments have default values that depend on each query. The after and last arguments are optional. The first and last arguments are mutually exclusive and cannot be used in the same query.

Field Values

Date Values Fields ending with ...At (for example, createdAt) are used to represent timestamp values. By default, timestamps are shown using the ISO-8601 format in the UTC timezone. You can select a different date format with the @dateFormat directive.

Username Values Fields ending with ...By (for example, createdBy) are used to represent the user who performed an action.

Experimental Features And Deprecations

Experimental features are marked with the @experimental directive. These are new features and may be subject to breaking changes in future releases.

Deprecations are marked with the @deprecated directive. Deprecated features are still available, but will be removed in future releases. Modify your queries according to the deprecation notice.