{"_id":"56312e0d82d96a0d00b0fb08","user":"554340dfb7f4540d00fcef1d","version":{"_id":"55faf11ba62ba1170021a9aa","project":"55faf11ba62ba1170021a9a7","__v":38,"createdAt":"2015-09-17T16:58:03.490Z","releaseDate":"2015-09-17T16:58:03.490Z","categories":["55faf11ca62ba1170021a9ab","55faf8f4d0e22017005b8272","55faf91aa62ba1170021a9b5","55faf929a8a7770d00c2c0bd","55faf932a8a7770d00c2c0bf","55faf94b17b9d00d00969f47","55faf958d0e22017005b8274","55faf95fa8a7770d00c2c0c0","55faf96917b9d00d00969f48","55faf970a8a7770d00c2c0c1","55faf98c825d5f19001fa3a6","55faf99aa62ba1170021a9b8","55faf99fa62ba1170021a9b9","55faf9aa17b9d00d00969f49","55faf9b6a8a7770d00c2c0c3","55faf9bda62ba1170021a9ba","5604570090ee490d00440551","5637e8b2fbe1c50d008cb078","5649bb624fa1460d00780add","5671974d1b6b730d008b4823","5671979d60c8e70d006c9760","568e8eef70ca1f0d0035808e","56d0a2081ecc471500f1795e","56d4a0adde40c70b00823ea3","56d96b03dd90610b00270849","56fbb83d8f21c817002af880","573c811bee2b3b2200422be1","576bc92afb62dd20001cda85","5771811e27a5c20e00030dcd","5785191af3a10c0e009b75b0","57bdf84d5d48411900cd8dc0","57ff5c5dc135231700aed806","5804caf792398f0f00e77521","58458b4fba4f1c0f009692bb","586d3c287c6b5b2300c05055","58ef66d88646742f009a0216","58f5d52d7891630f00fe4e77","59a555bccdbd85001bfb1442"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"57bdf84d5d48411900cd8dc0","version":"55faf11ba62ba1170021a9aa","__v":0,"project":"55faf11ba62ba1170021a9a7","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-08-24T19:41:01.302Z","from_sync":false,"order":26,"slug":"api-hub","title":"API Hub"},"parentDoc":null,"__v":74,"project":"55faf11ba62ba1170021a9a7","updates":["56a5e756525d8f170038ed8f","56a5f191fb12a40d006c4755"],"next":{"pages":[],"description":""},"createdAt":"2015-10-28T20:20:29.380Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"The CGC API uses the REST architectural style to read and write information about projects on the CGC. The API can be used to integrate the CGC with other applications, and to automate most procedures on it, such as uploading files, querying metadata, and executing analyses.\n\nThe base path of the API is: https://cgc-api.sbgenomics.com/v2\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"On this page\",\n  \"body\": \"* [API paths](doc:the-cgc-api#section-api-paths)\\n* [General API information](doc:the-cgc-api#section-general-api-information)\\n* [Identifying projects, users, apps, files, tasks and inputs](doc:the-cgc-api#section-identifying-projects-users-apps-files-tasks-and-inputs)\\n* [Authentication](doc:the-cgc-api#section-authentication)\\n* [Rate limits](doc:the-cgc-api#section-rate-limits)\\n* [Response pagination](doc:the-cgc-api#section-response-pagination)\"\n}\n[/block]\n##API paths\nThe paths are structured into the following endpoints, which cover different categories of activity on the CGC:\n  * [/action](http://docs.cancergenomicscloud.org/docs/actions)\n  * [/rate_limit](http://docs.cancergenomicscloud.org/docs/rate-limit)\n  * [/user](doc:user) \n  * [/users](http://docs.cancergenomicscloud.org/docs/users)\n  * [/billing](http://docs.cancergenomicscloud.org/docs/billing)\n  * [/projects](http://docs.cancergenomicscloud.org/docs/projects)\n  * [/files](http://docs.cancergenomicscloud.org/docs/files)\n  * [/upload](http://docs.cancergenomicscloud.org/docs/upload-files)\n  * [/apps](http://docs.cancergenomicscloud.org/docs/apps)\n  * [/tasks](http://docs.cancergenomicscloud.org/docs/tasks)\n  * [/storage](doc:volumes-v2)\n\n\n## General API information\n### Format\nAPI requests are made over HTTP, and information is received and sent in [JSON](https://en.wikipedia.org/wiki/JSON) format. For this reason, you should set both the `accept` and the `content` header of the request to `application/json`.\n\nResponses also include CGC-specific error codes, in addition to standard HTTP codes. Information about each code is available on the page [API status codes](doc:api-status-codes).\n\n### Generic query parameters\nAll API calls take the optional query parameter `fields`. This parameter enables you to specify the fields you want to be returned when listing resources (e.g. all your projects) or getting details of a specific resource (e.g. a given project).\n\nThe `fields` parameter can be used in the following ways:\n1. No `fields` parameter specified: calls return default fields. For calls that return complete details of a single resource, this is all their properties; for calls that list resources of a certain type, this is some default properties.\n2. The `fields` parameter can be set to a list of fields: for example, to return the fields `id`, `name` and `size` for files in a project, you may issue the call `GET /v2/files?project=john_doe/project1&fields=id,name,size`. The same goes for a call to get details of a specific file.\n3. The `fields` parameter can be used to exclude a specific file: if you wish to omit certain field from the response, do so using the `fields` parameter with the prefix `!`: for example, to get the details of a file without listing its metadata, issue a call `GET /v2/files/564a31c1e4b0ef12181758b0?fields=!metadata`. The entire metadata field will be removed from the response.\n4. The `fields` parameter can be used to include or omit certain nested fields, in the same way as listed in 2 and 3 above: for example, you can use `metadata.sample_id` or `origin.task` for files.\n5. To see all fields for a resource, specify `fields=_all`. This returns all fields for each resource returned. Note that if you are getting the details of a specific resource, the use of `fields=_all` won't return any more properties than would have been shown without this parameter – the use case is instead for when you are listing details of many resources. Please use with care if your resource has particularly large fields; for example, the `raw` field for an app resource contains the complete CWL specification of the app which can result in bulky response if listing many apps.\n6. Negations and nesting can be combined freely, so, for example, you can issue `GET /v2/files?fields=id,name,status,!metadata.library,!origin` or `GET /v2/tasks?fields=!inputs,!outputs`.\n\n\n## Identifying projects, users, apps, files, tasks and inputs\n###Project short names\nProjects on the CGC have both given names, which you will see in visual interfaces, like the Projects drop-down menu on the visual interface, and **short names**, which are human-readable IDs derived from the given names. To refer to a project in an API call, you should use its **short name**. \n\nProject **short names** are based on the name you give to a project when you create it. The short name is derived from the project name by:\n  * Formatting the name in lower case\n  * Omitting special characters, that are not letters, numbers, spaces or underscores\n  * Replacing spaces with hyphens\n  * Replacing underscores with hyphens\n  * Adding `_1` to any name that is already assigned to one of your projects.\n\nFor example, if I give my project the name 'RFranklin's experiments', it would be automatically assigned the short name 'rfranklins-experiments'. \n\nYou can optionally override an auto-assigned short names to one of your choice, when you create a project. To create your own project short name, first create a project, using the drop-down menu at the top of the screen. Then, click the pencil icon on the **Create a project** pop-out window.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/11rVR0qNQtmbDtXhcTXz_Screen%20Shot%202015-11-30%20at%2013.18.36.png\",\n        \"Screen Shot 2015-11-30 at 13.18.36.png\",\n        \"864\",\n        \"688\",\n        \"#38644c\",\n        \"\"\n      ],\n      \"caption\": \"Click the pencil icon to edit the project short name.\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/JrWwEX7lTVVAUGeL584S_Screen%20Shot%202015-12-01%20at%2011.34.59.png\",\n        \"Screen Shot 2015-12-01 at 11.34.59.png\",\n        \"708\",\n        \"72\",\n        \"#3d9be0\",\n        \"\"\n      ],\n      \"caption\": \"To check a project's **short name**, or a task or file's ID, you can inspect the URL when you click on the object in the browser.\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Changing a project's name\",\n  \"body\": \"Note that once the project has been created, **you cannot change its short name**. However, you can [edit a project's given name at any time](edit-a-specified-project).\"\n}\n[/block]\n###Users\nCGC Users are referred to in the API by their usernames. These are chosen by the user at the point at which they sign up for the CGC. Usernames are unique and immutable. They are also case sensitive, so it is advisable to user lower case strings for your username to avoid ambiguity.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Uniqueness of project names\",\n  \"body\": \"Every project is uniquely identified by `{project_owner_username}/{shortname}`.\"\n}\n[/block]\n###Apps\nApps (tools and workflows) in projects can be accessed using the API. Like projects, apps have both given names, which are assigned by the users who create them, and **short names** An app's short name is derived by the same process as a project's short name.\n\nEach app is identified with reference to the project it is contained in and its short name, using the format: `{project_owner}/{project}/{app_short_name}/{revision_number}`.\n\nFor instance, `RFranklin/my-project/bamtools-merge-2-4-0/0` identifies an app.\n\n###Tasks\nTasks are referred to in the API calls by IDs. These are hexadecimal strings ([UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier)) assigned to tasks. You can retrieve them by making the [API call to list tasks](http://docs.cancergenomicscloud.org/docs/list-tasks-you-can-access). \n\nTasks have the following statuses: `DRAFT`, `RUNNING`, `QUEUED`, `ABORTED`, `COMPLETED` or `FAILED`.\n\n###Files\nFiles are referred to in API calls by IDs. These are hexadecimal strings assigned to files. You can retrieve them by making the [API call to list files](http://docs.cancergenomicscloud.org/docs/list-files-in-a-project). \n\nNote that file IDs are dependent on the project the file is stored in. If you copy a file to a different project, it will have a new ID in this project.\n\nIn calls that return CWL descriptions of tasks, such as the call to [`GET` task details](http://docs.cancergenomicscloud.org/v1.0/docs/get-details-of-a-task), files are identified by their `path` objects. The file `path` is identical to the file ID.\n\n###Inputs\nTask inputs are specified as dictionaries. They pair apps to be executed in the task with the objects that will be inputted to them.\n\nThe format for an input is:\n`{app_id}: {object}`\n\nThe `{app_id}` is defined above. The value of `{object}` is obtained as follows:\nIf the object to be inputted to the task is not a file (but an integer, boolean, etc) then simply enter that value as `{object}`.\nIf the object to be inputted to the task is a file, then `{object}` is a dictionary, with the format:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n   \\\"class\\\": \\\"File\\\",\\n   \\\"path\\\": \\\"file_id\\\",\\n   \\\"name\\\": \\\"file_name.ext\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"{object}\"\n    }\n  ]\n}\n[/block]\nWhen multiple files are used as inputs, enter a list of `{object}`s, like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[\\n  {\\n  \\t \\\"class\\\": \\\"File\\\",\\n  \\t \\\"path\\\": \\\"file_id\\\",\\n  \\t \\\"name\\\": \\\"file_name.ext\\\"\\n\\t}\\n\\t{\\n \\t  \\\"class\\\": \\\"File\\\",\\n \\t  \\\"path\\\": \\\"file_id\\\",\\n \\t  \\\"name\\\": \\\"file_name.ext\\\"\\n\\t}\\n]\",\n      \"language\": \"json\",\n      \"name\": \"{object}s\"\n    }\n  ]\n}\n[/block]\nThe following are all examples of inputs:\n1. An input integer:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"Offset\\\": {2}\",\n      \"language\": \"json\",\n      \"name\": \"Example 1\"\n    }\n  ]\n}\n[/block]\n2. An input file for the known indels:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n        \\\"cuffdiff_zip\\\": {\\n            \\\"class\\\": \\\"File\\\",\\n            \\\"path\\\": \\\"562785e6e4b00a1d67a8b1aa\\\",\\n            \\\"name\\\": \\\"example_human_known_indels.vcf\\\"\\n        }\\n    }\",\n      \"language\": \"json\",\n      \"name\": \"Example 2\"\n    }\n  ]\n}\n[/block]\n3: File inputs for a Whole Exome Sequencing workflow, in the form of FASTQ reads:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"Reads_FASTQ\\\": [\\n    {\\n      \\\"class\\\": \\\"File\\\",\\n      \\\"path\\\": \\\"5602a18fe4b03d3ad9f1547b\\\",\\n      \\\"name\\\": \\\"WES_human_Illumina.pe_1.fastq\\\"\\n    },\\n    {\\n      \\\"class\\\": \\\"File\\\",\\n      \\\"path\\\": \\\"5602a18fe4b03d3ad9f15481\\\",\\n      \\\"name\\\": \\\"WES_human_Illumina.pe_2.fastq\\\"\\n    }\\n  ]\",\n      \"language\": \"json\",\n      \"name\": \"Example 3\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Task inputs\",\n  \"body\": \"For more examples of task `inputs`, use the call to [get task inputs](doc:get-task-inputs) for some of the tasks you initiate on the CGC visual interface.\\nFor finding which app receives which inputs and their format, you can review the app's page on the CGC visual interface. For example [Whole Exome Sequencing GATK 2.3.9.-lite](https://cgc.sbgenomics.com/public/apps/#workflow/djordje_klisic/public-apps-by-seven-bridges/whole-exome-sequencing-gatk-2-3-9-lite/)\"\n}\n[/block]\n## Authentication\nTo set your CGC credentials on the API, you will need an authentication token, which you can obtain from https://cgc.sbgenomics.com/account/#developer.\n\nAll API requests need to have the HTTP header `X-SBG-Auth-Token` which you should set to your authentication token. The only call which is exempt from this is the '/' call to list all request paths.\n\n## Rate limits\nAll API calls are rate-limited, which means that you can only perform a limited number of requests hourly. All rate limit information is returned to the user in the following HTTP headers:\n1. The header `X-RateLimit-Limit` represents the rate limit - currently this is 1000 requests per 5 minutes.\n2. The header `X-RateLimit-Remaining` represents your remaining number of calls before hitting the limit.\n3. The header `X-RateLimit-Reset` - represents the time in Unix timestamp when the limit will be reset\n\n\n## Response pagination\nAll API calls take the pagination query parameters `limit` and `offset` to control the number of items returned in a response. These are useful if you are returning information about a resource with many items, such as a list of many files in a project.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"In addition to controlling the number of items returned using the pagination query parameters, if you are requesting information about files using the call to [`GET /files`](http://docs.sevenbridges.com/docs/list-files-primary-method) you can filter items returned by filename, metadata, or originating task.\",\n  \"title\": \"Filtering\"\n}\n[/block]\n###Specify the number of items to return in a response\nYou can control how many items are returned by an API call using the query parameter `limit`. If you do not specify a value for `limit` in a call, a maximum of 50 items will be returned by the call by default. \n\nThe maximum value for the query parameter `limit` is 100.\n\nExample 1:\nSuppose you have 70 files in the project `my-project`, and you issue the call to [`GET /files`](http://docs.sevenbridges.com/docs/list-files-primary-method) as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /v2/files?project=my-project HTTP/1.1\\nHost: api.sbgenomics.com\\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nSince no value for `limit` was specified, this call will return details of 50 of the files, along with a URL to return the next 20. \n\nExample 2:\nAgain, suppose you have a project `my-project` with 70 files in it. The following call will return details of all 70 files\"\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /v2/files?project=my-project?limit=70 HTTP/1.1\\nHost: api.sbgenomics.com\\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n\n###Specify the starting point for items to return in a response\nYou can control the starting point at which to start returning items in an API call using the query parameter `offset`. If you do not specify a value for `offset` then the default starting point will be the first item in the specified resource. Specifying an integer value for `offset` will start from the item which is the one after the specified integer value.\n\nExample 1:\nSuppose you have a project called `my-project` containing 70 files, and you want to return their details, starting with the 31st file. To do this,  issue the call to [`GET /files`](http://docs.sevenbridges.com/docs/list-files-primary-method) with a query parameter `offset` specified as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /v2/files?project=my-project?offset=30 HTTP/1.1\\nHost: api.sbgenomics.com\\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n\nCalls made with the `offset` query parameter additionally return the header `X-Total-Matching-Query` which signifies the total number of results.\n\nExample 2:\nAn example of a call made using both pagination parameters is as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET v2/projects?limit=2&offset=2 HTTP/1.1\\nHost: api.sbgenomics.com\\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nThis returns the following body in JSON:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n \\\"href\\\": \\\"https://api.sbgenomics.com/v2/projects/\\\",\\n \\\"items\\\": [\\n {\\n \\\"href\\\": \\\"https://api.sbgenomics.com/v2/projects/john_doe/project1\\\",\\n \\\"id\\\": \\\"john_doe/project1\\\",\\n \\\"name\\\": \\\"project1\\\"\\n },\\n {\\n \\\"href\\\": \\\"https://api.sbgenomics.com/v2/projects/john_doe/project2\\\",\\n \\\"id\\\": \\\"john_doe/project2\\\",\\n \\\"name\\\": \\\"Project 2\\\"\\n }\\n ],\\n \\\"links\\\": [\\n {\\n \\\"href\\\": \\\"http://api.sbgenomics.com/v2/projects/?offset=4?limit=2\\\",\\n \\\"rel\\\": \\\"next\\\",\\n \\\"method\\\": \\\"GET\\\"\\n }\\n ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe headers returned include `X-Total-Matching-Query` which lists the total number of results.\nThe body of the response includes the array `links`, which indicate how to get the next or previous set of results.","excerpt":"","slug":"the-cgc-api","type":"basic","title":"API Overview"}
The CGC API uses the REST architectural style to read and write information about projects on the CGC. The API can be used to integrate the CGC with other applications, and to automate most procedures on it, such as uploading files, querying metadata, and executing analyses. The base path of the API is: https://cgc-api.sbgenomics.com/v2 [block:callout] { "type": "warning", "title": "On this page", "body": "* [API paths](doc:the-cgc-api#section-api-paths)\n* [General API information](doc:the-cgc-api#section-general-api-information)\n* [Identifying projects, users, apps, files, tasks and inputs](doc:the-cgc-api#section-identifying-projects-users-apps-files-tasks-and-inputs)\n* [Authentication](doc:the-cgc-api#section-authentication)\n* [Rate limits](doc:the-cgc-api#section-rate-limits)\n* [Response pagination](doc:the-cgc-api#section-response-pagination)" } [/block] ##API paths The paths are structured into the following endpoints, which cover different categories of activity on the CGC: * [/action](http://docs.cancergenomicscloud.org/docs/actions) * [/rate_limit](http://docs.cancergenomicscloud.org/docs/rate-limit) * [/user](doc:user) * [/users](http://docs.cancergenomicscloud.org/docs/users) * [/billing](http://docs.cancergenomicscloud.org/docs/billing) * [/projects](http://docs.cancergenomicscloud.org/docs/projects) * [/files](http://docs.cancergenomicscloud.org/docs/files) * [/upload](http://docs.cancergenomicscloud.org/docs/upload-files) * [/apps](http://docs.cancergenomicscloud.org/docs/apps) * [/tasks](http://docs.cancergenomicscloud.org/docs/tasks) * [/storage](doc:volumes-v2) ## General API information ### Format API requests are made over HTTP, and information is received and sent in [JSON](https://en.wikipedia.org/wiki/JSON) format. For this reason, you should set both the `accept` and the `content` header of the request to `application/json`. Responses also include CGC-specific error codes, in addition to standard HTTP codes. Information about each code is available on the page [API status codes](doc:api-status-codes). ### Generic query parameters All API calls take the optional query parameter `fields`. This parameter enables you to specify the fields you want to be returned when listing resources (e.g. all your projects) or getting details of a specific resource (e.g. a given project). The `fields` parameter can be used in the following ways: 1. No `fields` parameter specified: calls return default fields. For calls that return complete details of a single resource, this is all their properties; for calls that list resources of a certain type, this is some default properties. 2. The `fields` parameter can be set to a list of fields: for example, to return the fields `id`, `name` and `size` for files in a project, you may issue the call `GET /v2/files?project=john_doe/project1&fields=id,name,size`. The same goes for a call to get details of a specific file. 3. The `fields` parameter can be used to exclude a specific file: if you wish to omit certain field from the response, do so using the `fields` parameter with the prefix `!`: for example, to get the details of a file without listing its metadata, issue a call `GET /v2/files/564a31c1e4b0ef12181758b0?fields=!metadata`. The entire metadata field will be removed from the response. 4. The `fields` parameter can be used to include or omit certain nested fields, in the same way as listed in 2 and 3 above: for example, you can use `metadata.sample_id` or `origin.task` for files. 5. To see all fields for a resource, specify `fields=_all`. This returns all fields for each resource returned. Note that if you are getting the details of a specific resource, the use of `fields=_all` won't return any more properties than would have been shown without this parameter – the use case is instead for when you are listing details of many resources. Please use with care if your resource has particularly large fields; for example, the `raw` field for an app resource contains the complete CWL specification of the app which can result in bulky response if listing many apps. 6. Negations and nesting can be combined freely, so, for example, you can issue `GET /v2/files?fields=id,name,status,!metadata.library,!origin` or `GET /v2/tasks?fields=!inputs,!outputs`. ## Identifying projects, users, apps, files, tasks and inputs ###Project short names Projects on the CGC have both given names, which you will see in visual interfaces, like the Projects drop-down menu on the visual interface, and **short names**, which are human-readable IDs derived from the given names. To refer to a project in an API call, you should use its **short name**. Project **short names** are based on the name you give to a project when you create it. The short name is derived from the project name by: * Formatting the name in lower case * Omitting special characters, that are not letters, numbers, spaces or underscores * Replacing spaces with hyphens * Replacing underscores with hyphens * Adding `_1` to any name that is already assigned to one of your projects. For example, if I give my project the name 'RFranklin's experiments', it would be automatically assigned the short name 'rfranklins-experiments'. You can optionally override an auto-assigned short names to one of your choice, when you create a project. To create your own project short name, first create a project, using the drop-down menu at the top of the screen. Then, click the pencil icon on the **Create a project** pop-out window. [block:image] { "images": [ { "image": [ "https://files.readme.io/11rVR0qNQtmbDtXhcTXz_Screen%20Shot%202015-11-30%20at%2013.18.36.png", "Screen Shot 2015-11-30 at 13.18.36.png", "864", "688", "#38644c", "" ], "caption": "Click the pencil icon to edit the project short name." } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/JrWwEX7lTVVAUGeL584S_Screen%20Shot%202015-12-01%20at%2011.34.59.png", "Screen Shot 2015-12-01 at 11.34.59.png", "708", "72", "#3d9be0", "" ], "caption": "To check a project's **short name**, or a task or file's ID, you can inspect the URL when you click on the object in the browser." } ] } [/block] [block:callout] { "type": "success", "title": "Changing a project's name", "body": "Note that once the project has been created, **you cannot change its short name**. However, you can [edit a project's given name at any time](edit-a-specified-project)." } [/block] ###Users CGC Users are referred to in the API by their usernames. These are chosen by the user at the point at which they sign up for the CGC. Usernames are unique and immutable. They are also case sensitive, so it is advisable to user lower case strings for your username to avoid ambiguity. [block:callout] { "type": "success", "title": "Uniqueness of project names", "body": "Every project is uniquely identified by `{project_owner_username}/{shortname}`." } [/block] ###Apps Apps (tools and workflows) in projects can be accessed using the API. Like projects, apps have both given names, which are assigned by the users who create them, and **short names** An app's short name is derived by the same process as a project's short name. Each app is identified with reference to the project it is contained in and its short name, using the format: `{project_owner}/{project}/{app_short_name}/{revision_number}`. For instance, `RFranklin/my-project/bamtools-merge-2-4-0/0` identifies an app. ###Tasks Tasks are referred to in the API calls by IDs. These are hexadecimal strings ([UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier)) assigned to tasks. You can retrieve them by making the [API call to list tasks](http://docs.cancergenomicscloud.org/docs/list-tasks-you-can-access). Tasks have the following statuses: `DRAFT`, `RUNNING`, `QUEUED`, `ABORTED`, `COMPLETED` or `FAILED`. ###Files Files are referred to in API calls by IDs. These are hexadecimal strings assigned to files. You can retrieve them by making the [API call to list files](http://docs.cancergenomicscloud.org/docs/list-files-in-a-project). Note that file IDs are dependent on the project the file is stored in. If you copy a file to a different project, it will have a new ID in this project. In calls that return CWL descriptions of tasks, such as the call to [`GET` task details](http://docs.cancergenomicscloud.org/v1.0/docs/get-details-of-a-task), files are identified by their `path` objects. The file `path` is identical to the file ID. ###Inputs Task inputs are specified as dictionaries. They pair apps to be executed in the task with the objects that will be inputted to them. The format for an input is: `{app_id}: {object}` The `{app_id}` is defined above. The value of `{object}` is obtained as follows: If the object to be inputted to the task is not a file (but an integer, boolean, etc) then simply enter that value as `{object}`. If the object to be inputted to the task is a file, then `{object}` is a dictionary, with the format: [block:code] { "codes": [ { "code": "{\n \"class\": \"File\",\n \"path\": \"file_id\",\n \"name\": \"file_name.ext\"\n}", "language": "json", "name": "{object}" } ] } [/block] When multiple files are used as inputs, enter a list of `{object}`s, like this: [block:code] { "codes": [ { "code": "[\n {\n \t \"class\": \"File\",\n \t \"path\": \"file_id\",\n \t \"name\": \"file_name.ext\"\n\t}\n\t{\n \t \"class\": \"File\",\n \t \"path\": \"file_id\",\n \t \"name\": \"file_name.ext\"\n\t}\n]", "language": "json", "name": "{object}s" } ] } [/block] The following are all examples of inputs: 1. An input integer: [block:code] { "codes": [ { "code": "\"Offset\": {2}", "language": "json", "name": "Example 1" } ] } [/block] 2. An input file for the known indels: [block:code] { "codes": [ { "code": "{\n \"cuffdiff_zip\": {\n \"class\": \"File\",\n \"path\": \"562785e6e4b00a1d67a8b1aa\",\n \"name\": \"example_human_known_indels.vcf\"\n }\n }", "language": "json", "name": "Example 2" } ] } [/block] 3: File inputs for a Whole Exome Sequencing workflow, in the form of FASTQ reads: [block:code] { "codes": [ { "code": "\"Reads_FASTQ\": [\n {\n \"class\": \"File\",\n \"path\": \"5602a18fe4b03d3ad9f1547b\",\n \"name\": \"WES_human_Illumina.pe_1.fastq\"\n },\n {\n \"class\": \"File\",\n \"path\": \"5602a18fe4b03d3ad9f15481\",\n \"name\": \"WES_human_Illumina.pe_2.fastq\"\n }\n ]", "language": "json", "name": "Example 3" } ] } [/block] [block:callout] { "type": "success", "title": "Task inputs", "body": "For more examples of task `inputs`, use the call to [get task inputs](doc:get-task-inputs) for some of the tasks you initiate on the CGC visual interface.\nFor finding which app receives which inputs and their format, you can review the app's page on the CGC visual interface. For example [Whole Exome Sequencing GATK 2.3.9.-lite](https://cgc.sbgenomics.com/public/apps/#workflow/djordje_klisic/public-apps-by-seven-bridges/whole-exome-sequencing-gatk-2-3-9-lite/)" } [/block] ## Authentication To set your CGC credentials on the API, you will need an authentication token, which you can obtain from https://cgc.sbgenomics.com/account/#developer. All API requests need to have the HTTP header `X-SBG-Auth-Token` which you should set to your authentication token. The only call which is exempt from this is the '/' call to list all request paths. ## Rate limits All API calls are rate-limited, which means that you can only perform a limited number of requests hourly. All rate limit information is returned to the user in the following HTTP headers: 1. The header `X-RateLimit-Limit` represents the rate limit - currently this is 1000 requests per 5 minutes. 2. The header `X-RateLimit-Remaining` represents your remaining number of calls before hitting the limit. 3. The header `X-RateLimit-Reset` - represents the time in Unix timestamp when the limit will be reset ## Response pagination All API calls take the pagination query parameters `limit` and `offset` to control the number of items returned in a response. These are useful if you are returning information about a resource with many items, such as a list of many files in a project. [block:callout] { "type": "success", "body": "In addition to controlling the number of items returned using the pagination query parameters, if you are requesting information about files using the call to [`GET /files`](http://docs.sevenbridges.com/docs/list-files-primary-method) you can filter items returned by filename, metadata, or originating task.", "title": "Filtering" } [/block] ###Specify the number of items to return in a response You can control how many items are returned by an API call using the query parameter `limit`. If you do not specify a value for `limit` in a call, a maximum of 50 items will be returned by the call by default. The maximum value for the query parameter `limit` is 100. Example 1: Suppose you have 70 files in the project `my-project`, and you issue the call to [`GET /files`](http://docs.sevenbridges.com/docs/list-files-primary-method) as follows: [block:code] { "codes": [ { "code": "GET /v2/files?project=my-project HTTP/1.1\nHost: api.sbgenomics.com\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74", "language": "http" } ] } [/block] Since no value for `limit` was specified, this call will return details of 50 of the files, along with a URL to return the next 20. Example 2: Again, suppose you have a project `my-project` with 70 files in it. The following call will return details of all 70 files" [block:code] { "codes": [ { "code": "GET /v2/files?project=my-project?limit=70 HTTP/1.1\nHost: api.sbgenomics.com\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74", "language": "http" } ] } [/block] ###Specify the starting point for items to return in a response You can control the starting point at which to start returning items in an API call using the query parameter `offset`. If you do not specify a value for `offset` then the default starting point will be the first item in the specified resource. Specifying an integer value for `offset` will start from the item which is the one after the specified integer value. Example 1: Suppose you have a project called `my-project` containing 70 files, and you want to return their details, starting with the 31st file. To do this, issue the call to [`GET /files`](http://docs.sevenbridges.com/docs/list-files-primary-method) with a query parameter `offset` specified as follows: [block:code] { "codes": [ { "code": "GET /v2/files?project=my-project?offset=30 HTTP/1.1\nHost: api.sbgenomics.com\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74", "language": "http" } ] } [/block] Calls made with the `offset` query parameter additionally return the header `X-Total-Matching-Query` which signifies the total number of results. Example 2: An example of a call made using both pagination parameters is as follows: [block:code] { "codes": [ { "code": "GET v2/projects?limit=2&offset=2 HTTP/1.1\nHost: api.sbgenomics.com\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74", "language": "http" } ] } [/block] This returns the following body in JSON: [block:code] { "codes": [ { "code": "{\n \"href\": \"https://api.sbgenomics.com/v2/projects/\",\n \"items\": [\n {\n \"href\": \"https://api.sbgenomics.com/v2/projects/john_doe/project1\",\n \"id\": \"john_doe/project1\",\n \"name\": \"project1\"\n },\n {\n \"href\": \"https://api.sbgenomics.com/v2/projects/john_doe/project2\",\n \"id\": \"john_doe/project2\",\n \"name\": \"Project 2\"\n }\n ],\n \"links\": [\n {\n \"href\": \"http://api.sbgenomics.com/v2/projects/?offset=4?limit=2\",\n \"rel\": \"next\",\n \"method\": \"GET\"\n }\n ]\n}", "language": "json" } ] } [/block] The headers returned include `X-Total-Matching-Query` which lists the total number of results. The body of the response includes the array `links`, which indicate how to get the next or previous set of results.