{ "opencollection": "1.0.0", "info": { "name": "Fence OpenAPI Specification admin/user data API", "version": "0.1.0" }, "items": [ { "info": { "name": "data", "type": "folder" }, "items": [ { "info": { "name": "delete all locations of a stored data file and remove its record from indexd", "type": "http" }, "http": { "method": "DELETE", "url": "https://example.domain/data/:file_id", "auth": { "type": "oauth2", "flow": "authorization_code", "authorizationUrl": "/oauth/authorize", "accessTokenUrl": "/oauth/token", "credentials": { "clientId": "{{clientId}}", "clientSecret": "{{clientSecret}}" } } }, "docs": "After a user uploads a data file and it is registered in indexd (before or after it is mapped into the graph via metadata submission), this endpoint will delete the file from its storage locations (saved in the record in indexd) and delete the record in indexd." }, { "info": { "name": "Create a signed URL for data download given a file_id", "type": "http" }, "http": { "method": "GET", "url": "https://example.domain/data/download/:file_id", "params": [ { "name": "file_id", "value": "", "type": "path", "description": "data UUID" }, { "name": "protocol", "value": "", "type": "query", "description": "a protocol provided by storage provider, e.g. http, ftp, s3, gs" }, { "name": "expires_in", "value": "", "type": "query", "description": "the time (in seconds) in which return url is valid. Must be less than the configured maximum (default is 3600). If it's greater, the configured maximum will be used." }, { "name": "redirect", "value": "", "type": "query", "description": "if set, then a redirect to the signed url will be sent. Otherwise, json data with the url is returned." }, { "name": "no_force_sign", "value": "", "type": "query", "description": "if `no_force_sign=True`, this will request to *not* sign the resulting URL (i.e. just provide the public url without using anonymous signing creds)." }, { "name": "userProject", "value": "", "type": "query", "description": "a Google Project to bill for accessing data in requester pays buckets in Google Storage. Will override any configured default billing projects. If Fence is configured to automatically attempt to provide the necessary service account(s) billing permission, the provided Google Project will need to have given the Fence admin service account necessary permissions to create custom roles and set Project IAM policies. Please see README for more information." } ], "auth": { "type": "oauth2", "flow": "authorization_code", "authorizationUrl": "/oauth/authorize", "accessTokenUrl": "/oauth/token", "credentials": { "clientId": "{{clientId}}", "clientSecret": "{{clientSecret}}" } } }, "docs": "Allow users to get a signed URL for a data file." }, { "info": { "name": "GA4GH DRS Access API to get a URL for fetching bytes.", "type": "http" }, "http": { "method": "GET", "url": "https://example.domain/ga4gh/drs/v1/objects/:object_id/access/:access_id", "params": [ { "name": "object_id", "value": "", "type": "path", "description": "An id of a DrsObject" }, { "name": "access_id", "value": "", "type": "path", "description": "An access_id from the access_methods list of a DrsObject" } ] }, "docs": "Returns a URL that can be used to fetch the bytes of a DrsObject. This method only needs to be called when using an AccessMethod that contains an access_id (e.g., for servers that use signed URLs for fetching object bytes)." }, { "info": { "name": "GA4GH DRS Access API to get a URL for fetching bytes.", "type": "http" }, "http": { "method": "POST", "url": "https://example.domain/ga4gh/drs/v1/objects/:object_id/access/:access_id", "params": [ { "name": "object_id", "value": "", "type": "path", "description": "An id of a DrsObject" }, { "name": "access_id", "value": "", "type": "path", "description": "An access_id from the access_methods list of a DrsObject" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Returns a URL that can be used to fetch the bytes of a DrsObject. This method only needs to be called when using an AccessMethod that contains an access_id (e.g., for servers that use signed URLs for fetching object bytes)." }, { "info": { "name": "Create a new blank record in indexd to use for uploading a data file less than 5GB. For files larger than 5GB, please use multipart upload presigned url", "type": "http" }, "http": { "method": "POST", "url": "https://example.domain/data/upload", "body": { "type": "json", "data": "{}" }, "auth": { "type": "oauth2", "flow": "authorization_code", "authorizationUrl": "/oauth/authorize", "accessTokenUrl": "/oauth/token", "credentials": { "clientId": "{{clientId}}", "clientSecret": "{{clientSecret}}" } } }, "docs": "This is the first step on the API side for the data upload flow. This\nendpoint causes fence to make a request to indexd to create a new, blank\nindex record, and returns the GUID for this new record and a presigned\nURL which a client can then use to upload their data file directly to a\nstorage bucket. No parameters are accepted because fence retrieves the\nusername from the current token to send to indexd for the `uploader`\nfield in the new record.\n\nThis API also supports utilizing the newer auth" }, { "info": { "name": "Create a signed URL for data upload specified by file_id", "type": "http" }, "http": { "method": "GET", "url": "https://example.domain/data/upload/:file_id", "params": [ { "name": "file_id", "value": "", "type": "path", "description": "data UUID" }, { "name": "protocol", "value": "", "type": "query", "description": "a protocol provided by storage provider, e.g. http, ftp, s3, gs" }, { "name": "expires_in", "value": "", "type": "query", "description": "the time (in seconds) in which return url is valid. Must be less than the configured maximum (default is 3600). If it's greater, the configured maximum will be used." }, { "name": "file_name", "value": "", "type": "query", "description": "the requested file name in the cloud bucket you will upload to. If not provided, will use the GUID/file_id" }, { "name": "bucket", "value": "", "type": "query", "description": "the requested bucket to upload to. If not provided, defaults to the configured DATA_UPLOAD_BUCKET." } ], "auth": { "type": "oauth2", "flow": "authorization_code", "authorizationUrl": "/oauth/authorize", "accessTokenUrl": "/oauth/token", "credentials": { "clientId": "{{clientId}}", "clientSecret": "{{clientSecret}}" } } }, "docs": "Allow users to get a signed URL to upload data given the location of preference." }, { "info": { "name": "Initilize a multipart upload for AWS bucket. It returns an uploadId which can be used for uploading object parts (see /multipart/upload) and completing the upload (see /multipart/complete)", "type": "http" }, "http": { "method": "POST", "url": "https://example.domain/multipart/init", "body": { "type": "json", "data": "{}" }, "auth": { "type": "oauth2", "flow": "authorization_code", "authorizationUrl": "/oauth/authorize", "accessTokenUrl": "/oauth/token", "credentials": { "clientId": "{{clientId}}", "clientSecret": "{{clientSecret}}" } } }, "docs": "For uploading the big file with the size is larger than 5GB in data upload flow, Fence needs to provide a list of endpoints for supporting multipart upload presigned url This is the first step on the API side for the multipart upload presigned url. This endpoint causes fence to make a request to indexd to create a new, blank index record, and returns the GUID for this new record and an uploadId for multipart upload presigned url.\n\nAccepts a \"guid\" field in the request body. If \"guid\" is provided" }, { "info": { "name": "Upload an object part given uploadId", "type": "http" }, "http": { "method": "POST", "url": "https://example.domain/multipart/upload", "body": { "type": "json", "data": "{}" }, "auth": { "type": "oauth2", "flow": "authorization_code", "authorizationUrl": "/oauth/authorize", "accessTokenUrl": "/oauth/token", "credentials": { "clientId": "{{clientId}}", "clientSecret": "{{clientSecret}}" } } }, "docs": "This is the second step on the API side for the multipart upload presigned url. The object is chopped into multiple parts with part number start from 1. Each part is submitted to the cloud resource with this endpoint by providing the part number a long with uploadId. It is worth to mention that the minimal supported part size is 5 MB as describe in https://docs.aws.amazon.com/AmazonS3/latest/dev/qfacts.html" }, { "info": { "name": "Complete aws multipart upload", "type": "http" }, "http": { "method": "POST", "url": "https://example.domain/multipart/complete", "body": { "type": "json", "data": "{}" }, "auth": { "type": "oauth2", "flow": "authorization_code", "authorizationUrl": "/oauth/authorize", "accessTokenUrl": "/oauth/token", "credentials": { "clientId": "{{clientId}}", "clientSecret": "{{clientSecret}}" } } }, "docs": "This is the last step for the multipart upload presigned url. All the parts which were submitted need to be combined together. This enpoint takes a list of the part info (partNumber, Etag) and uploadId in order to finish the upload" }, { "info": { "name": "Get list of buckets and relevant bucket info", "type": "http" }, "http": { "method": "GET", "url": "https://example.domain/data/buckets" }, "docs": "Returns a list of buckets and relevant bucket information provided in the fence-config under AWS_BUCKETS and GS_BUCKETS. It filters out sensitive information about the bucket and only shows information like bucket region." } ] } ], "bundled": true }