{"id":19792003,"url":"https://github.com/xray-app/xray-postman-collections","last_synced_at":"2025-10-31T17:30:27.482Z","repository":{"id":98610981,"uuid":"276587001","full_name":"Xray-App/xray-postman-collections","owner":"Xray-App","description":"Xray Test Management Postman collections for public APIs","archived":false,"fork":false,"pushed_at":"2024-08-14T09:08:32.000Z","size":2816,"stargazers_count":44,"open_issues_count":0,"forks_count":43,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-02-07T05:07:09.999Z","etag":null,"topics":["api","postman","postman-collection","testing","testing-tools","xray"],"latest_commit_sha":null,"homepage":"","language":"Gherkin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Xray-App.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-02T08:09:10.000Z","updated_at":"2024-11-01T08:03:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"308df2f0-0f02-42ee-8fd2-b77fa6140f8f","html_url":"https://github.com/Xray-App/xray-postman-collections","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xray-App%2Fxray-postman-collections","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xray-App%2Fxray-postman-collections/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xray-App%2Fxray-postman-collections/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xray-App%2Fxray-postman-collections/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Xray-App","download_url":"https://codeload.github.com/Xray-App/xray-postman-collections/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239217106,"owners_count":19601594,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","postman","postman-collection","testing","testing-tools","xray"],"created_at":"2024-11-12T07:05:41.089Z","updated_at":"2025-10-31T17:30:27.451Z","avatar_url":"https://github.com/Xray-App.png","language":"Gherkin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Xray Postman Collections\n\n[![license](https://img.shields.io/badge/License-BSD%203--Clause-green.svg)](https://opensource.org/licenses/BSD-3-Clause)\n[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/Xray-App/community)\n\n\n- [Xray Postman Collections](#xray-postman-collections)\n  * [Collections organization](#collections-organization)\n  * [How to use the collections](#how-to-use-the-collections)\n  * [APIs](#apis)\n    + [Xray server (i.e. on Jira server/Datacenter)](#xray-server--ie-on-jira-server-datacenter-)\n      - [REST API v1.0](#rest-api-v10)\n      - [REST API v2.0](#rest-api-v20)\n    + [Xray Cloud (i.e. on Jira Cloud)](#xray-cloud--ie-on-jira-cloud-)\n      - [REST API v1](#rest-api-v1)\n      - [GraphQL](#graphql)\n  * [Questions](#questions)\n  * [TO DO](#to-do)\n  * [Disclaimer](#disclaimer)\n  * [License](#license)\n\n\u003csmall\u003e\u003ci\u003e\u003ca href='http://ecotrust-canada.github.io/markdown-toc/'\u003eTable of contents generated with markdown-toc\u003c/a\u003e\u003c/i\u003e\u003c/small\u003e\n\n![Xray Postman Collections](postman_collections_example.png)\n\nHere you can find some Postman collections that exemplify usage of [Xray Test Management](https://www.getxray.app/) public APIs.\nThe idea is to have some concrete examples of how to make certain, basic requests. Then you can play with them and adapt to your needs. It's easier to learn by example, isn't it?\n\nAPIs are used to obtain and update data; in Xray, most times they are used to import results from automation frameworks.\nHowever, APIs allow to do a lot more: obtain entities, their relations and modify/delete them.\n\nAlthough similar, Xray server/datacenter and Xray on Jira cloud are two different products with also slight different characteristics.\nXray on Jira server/DC has a pubic REST API. Xray on Jira Cloud has a REST API along with a GraphQL API. We'll discuss this ahead.\n\n## Collections organization\n\nThe collection starts by some initial requests that populate the destination Jira instance with some data that will be used by the requests of the collection. These test data initialization requests are stored under the \"setup\" folder and will populate some global variables used by subsequent requests.\n\nThe actual requests are organized in multiple folders and subfolders, by the semantics of the requests/URL of endpoint calls. Each request has some basic Postman tests implemented as such, so you can assess their behaviour.\n\n**Note:** Some few requests depend on the outcomes of previous requests.\n\n## How to use the collections\n\nFirst of all, you'll need [Postman](https://www.postman.com/) :-)\nIn Postman **you need to configure variables related to your Xray/Jira instance**.\nYou can adjust them at collection level, or even better, at environment level in Postman.\n\n**Server specific variables, usually defined within a Postman environment**\n\n Variable          | example                                           \n-------------------| --------------------------------------------------\n JIRA_BASEURL      | https://sandbox.getxray.app                      \n JIRA_USERNAME     | sergio                                            \n JIRA_PASSWORD     | xxxxxx    \n CF_Test_Type      | customfield_10200\n CF_Precondition_Type   | customfield_10220\n CF_Cucumber_Scenario   | customfield_10202\n CF_Cucumber_Test_Type  | customfield_10201\n CF_Manual_Test_Steps   | customfield_10204\n CF_Generic_Definition  | customfield_10203\n CF_Test_Environments   | customfield_10224\n CF_Test_Repository_Path| customfield_10210\n TEST_ISSUETYPE_NAME    | Test\n PRECONDITION_ISSUETYPE_NAME  | Pre-Condition\n TESTSET_ISSUETYPE_NAME       | Test Set\n TESTEXECUTION_ISSUETYPE_NAME | Test Execution\n TESTPLAN_ISSUETYPE_NAME  | Test Plan\n PROJECT_KEY          | CALC\n BUG_ISSUETYPE_NAME   | Bug\n STORY_ISSUETYPE_NAME | Story\n XRAY_VERSION_MAJOR   | 4 (always use this value)\n\n\n**Example of environment configuration**\n\n![Xray server/DC variables defined at environment level](server_variables.png)\n\n\n**Cloud specific variables, usually defined within a Postman environment**\n\n Variable          | example                                           \n-------------------| --------------------------------------------------\n client_id         | 0011233... (obtained from a Xray API \"key\")      \n client_secret      | 0011233... (obtained from a Xray API \"key\")       \n JIRA_BASEURL      | https://sergiofreire.atlassian.net                \n JIRA_USERNAME     | sergio.freire@example.com                         \n JIRA_PASSWORD     | xxxxxx   (JIRA Api token)\n\n**Example of environment configuration**\n\n![environment variables](cloud_collection_variables.png)\n\n![Xray cloud variables defined at environment level](image.png)\n\nAfter adjusting the variables, it is recommended to run the requests in bulk using the collection runner in order to populate the variables (you could also run just the \"setup\" related requests).\nAfterwards, you can send requests individually right from Postman's main screen (i.e. the editor).\n\n## APIs\n\nThere are several APIs used to interact with Xray related entities:\n\n- Jira REST API\n- Xray REST API\n- Xray GraphQL\n\nJira REST API can be used to access and manipulate Jira related entities (e.g. issues). As most Xray entities are issue type based, then you can create, delete and even update (to an extent) these using Jira REST API calls. As an example, creating a Test issue can be done using Jira REST API /issue call.\nIn order to use Jira REST API you need to authenticate (e.g. using basic auth and the Jira user credentials). More on Jira server/DC REST API [here](https://developer.atlassian.com/server/jira/platform/rest-apis/).\nIn [Jira Cloud](https://developer.atlassian.com/cloud/jira/platform/rest/) you need to use [API tokens](https://confluence.atlassian.com/cloud/api-tokens-938839638.html) and authenticate using them.\n\nXray REST APIs are used to manipulate data (e.g. importing results, obtain relations between entities); for historical reasons, Xray server/DC provides an extensive set of endpoints. The Xray REST API in Xray cloud is much more limited (GraphQL is preferred instead).\nAs Xray server/DC provides the REST API on top of Jira's REST API, it reuses the same authentication mechanisms provided by Jira (e.g. basic auth, OAuth).\nIn Xray cloud, a [specific authentication mechanism](https://docs.getxray.app/display/XRAYCLOUD/Authentication+-+REST) is used instead.\n\nXray GraphQL, as of July 2020, is only available in Xray on Jira cloud. It provides an extensive set of features, allowing you to query and update Xray related data. This is the preferred API for Xray cloud, even though some features (e.g. importing results) are only available in the Xray REST API.\n\n### Xray server (i.e. on Jira server/Datacenter)\n\n#### REST API v1.0\n\n[Version 1.0](https://docs.getxray.app/display/XRAY/v1.0) has been provided until Xray v3.6.x.\nIt provides the ability to obtain and update Xray related entities and their relations. It also provides the necessary endpoints to import/export tests and test results.\nUnfortunately, not all endpoints are RESTful compliant due to some minor incompabilities.\nXray REST API reuses the same authentication mechanism used by Jira's REST API.\n\nExamples for this API are provided in [this collection](Xray_REST_API_v1.0.postman_collection.json).\n\n#### REST API v2.0\n\n[Version 2.0](https://docs.getxray.app/display/XRAY/v2.0) is available since Xray v4.0. This is an evolution over the previous Xray REST v1.0 version, providing additional endpoints for dealing with test step and test run custom fields.\nXray REST API reuses the same authentication mechanism used by Jira's REST API.\n\nExamples for this API are provided in [this collection](Xray_REST_API_v2.0.postman_collection.json).\n\n### Xray Cloud (i.e. on Jira Cloud)\n\nBefore performing any request on Xray related endpoints, you'll need to have a [Xray API key](https://docs.getxray.app/display/XRAYCLOUD/Global+Settings%3A+API+Keys) (i.e. client_id + client_secret), so that you can authenticate against Xray (more info [here](https://docs.getxray.app/display/XRAYCLOUD/Authentication+-+REST)).\nThis will create a token that you'll need to use in following requests.\n\nNote: Xray cloud APIs are rate/resource limited, so you should have that in mind. More info [here](https://docs.getxray.app/display/XRAYCLOUD/GraphQL+API).\n\nExamples for the public APIs (REST and GraphQL based) are provided in the same [collection](Xray_Cloud_GraphQL_API.postman_collection.json).\n\nYou need to define some variables (client_id, client_secret) in a Postman environment used and assigned to run the collection.\n\n#### REST API v1\n\nXray cloud provides a [basic REST API](https://docs.getxray.app/display/XRAYCLOUD/REST+API) that is mostly used to import test automation related results, similarly to the Xray server/DC REST APIs.\nThere are some additional, unrelated calls though.\nNote that GraphQL is the preferred API for managing entities.\nYour requests need to be authenticated, using the token obtained in the respective REST API v1 call mentioned earlier.\n\n#### GraphQL\n\nBesides a basic REST API, Xray cloud also provides a [GraphQL API](https://docs.getxray.app/display/XRAYCLOUD/GraphQL+API) which is quite extensive and allows to query and updte data easily.\nQuerying with GraphQL is more flexible and efficient, as you can make one request to obtain entities, the fields you needs, relations, fields on the related entities, etc.\nYour requests need to be authenticated, using the token obtained in the respective REST API v1 call mentioned earlier.\n\nNote: GraphQL is instrospective, so you should be able to use it rightaway if your client support it. The [Insomnia tool](https://insomnia.rest/) tool supports this; Postman not yet, as of July 2020.\n\n## Questions\n\n* _What happens if I run the whole collection?_\nSome data, including Jira issues, will be created on the destination instance\n\n* _Will this delete any existing data in my Jira instance?_\nIt shouldn't but it depends on your usage. Please see the disclaimer ahead.\n\n* _I have some questions..._\nWell, if you have a Xray license, including trials, you can reach out to Xray support for general API and Xray usage questions. However, questions related to this specific open-source project are not covered/handled by Xray support.\n\n* _I have some suggestions..._\nYou can reach out to me on [Twitter](https://www.twitter.com/darktelecom). However, please don't use to make support requests :)\n\n* _Do you have some environment where I can test this on?_\nFor Xray on Jira server/DC you can use our sandbox environment; you'll need to crete a Jira user there.\nFor Xray on Jira cloud, you can create a free Jira cloud instance and then install the Xray app.\nIn any case, you'll need to have a Jira project pre-created and configured properly with Xray entities.\n\n* _Can I use these collections in my existent Jira instance?_\nYes, at your own risk :-)\nIf you want to perform some tests, you should create a specific playground kind of project. Read-type of requests can be performed on any existing project.\n\n* _What is the best way to manage variables in Postman?_\nYou can keep some variables at the collection level and other at the enviroment level. Well, you can put all your collection variables inside a Postman environment and manage it there, since they will most proabably change between different Jira instances.\n\n## TO DO\n\n- cleanup variable names and some redundancy\n- evaluate usage of global variables\n- import automation results using multipart endpoints\n\n## Disclaimer\n\nThis collection is provided as-is. No guarantees whatsoever.\n\n## License\n\n[BSD 3-clause](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxray-app%2Fxray-postman-collections","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxray-app%2Fxray-postman-collections","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxray-app%2Fxray-postman-collections/lists"}