JFrog Artifactory provides powerful REST APIs to manage and automate your artifact workflows, including the management of release bundles.
For users who are dealing with Release Bundle v2 and need to retrieve specific records related to bundle promotions, JFrog offers a convenient API to filter and order these records based on specific criteria.
This article will guide you on how to use the filter_by and order_by parameters effectively to fetch the promoted release bundle details.
The Get Release Bundle REST API: Get Release Bundle v2 Promotions
To retrieve information about promoted release bundles in Artifactory, you can use the Get Release Bundle v2 Promotions REST API.
This API provides you with a way to filter and organize records based on a variety of parameters such as the environment, release bundle version, and project details.
The basic format of the API endpoint looks like this:
GET https://artifactory.com/lifecycle/api/v2/promotion/records/<release-bundle-name>
This command retrieves the details of the release bundle, but with the addition of the filter_by and order_by parameters, you can narrow down the results and tailor them to your specific needs.
Using the filter_by Parameter to Fetch Records in a Specific Environment
One of the most useful features of the Get Release Bundle v2 Promotions API is the filter_by parameter.
This parameter allows you to filter records based on specific criteria, such as the environment in which the release bundle was promoted.
By using this filter, you can easily retrieve only the release bundles that have been promoted to a particular environment.
For example, if you want to fetch details for release bundles that have been promoted to the production environment, you can use the following API command:
GET https://artifactory.com/lifecycle/api/v2/promotion/records/<release-bundle-name>?project=default&filter_by=production
Here’s a breakdown of the URL components:
- <release-bundle-name>: Replace this with the name of your specific release bundle.
- project=default: This is optional, but if you have a project name, you can specify it here to further scope the results.
- filter_by=production: This will filter the release bundles to only show those that were promoted to the production environment.
This command will return only the release bundles associated with the production environment.
You can replace production with any environment name that is relevant to your use case.
Using the order_by Parameter to Sort Records by Version
The order_by parameter allows you to sort the records based on a specific field.
In the case of release bundles, you may want to sort the results by the release bundle version to ensure you retrieve the latest or most relevant records.
For example, if you want to retrieve the most recent version of a specific release bundle in the production environment and order the results by version, you can use the following API command:
GET https://artifactory.com/lifecycle/api/v2/promotion/records/<release-bundle-name>?project=default&filter_by=environment&order_by=release_bundle_version
Example of Complete API Call
Let’s say you have a release bundle named my-release-bundle and you want to fetch its details for the production environment, ordered by version, while optionally specifying a project.
The API call would look like this
GET https://artifactory.com/lifecycle/api/v2/promotion/records/my-release-bundle?project=my-project&filter_by=PROD&order_by=release_bundle_version
Optional: Specifying a Project Name
As mentioned, the project parameter is optional.
If you are working within a specific project context and wish to scope the results to a particular project, you can add it to the API command as shown in the examples above.
However, if you don't need this, you can omit the project parameter altogether.
For additional query parameters, fields, and filter options, please refer to the JFrog REST API documentation page.
Conclusion
By utilizing the filter_by and order_by parameters, you can efficiently retrieve and organize details about promoted release bundles in Artifactory.
These parameters allow you to filter by specific environments and order the results by release bundle version, ensuring that you can quickly access the information that matters most to your workflow.
For more information on the release bundle v2 REST API, be sure to check the JFrog documentation and watch for updates on the JIRA enhancement request to further enhance your experience with the Release Bundle v2 API.
If you have any questions or need further assistance, feel free to reach out to JFrog support.