1. Implementation Guide
  2. Uploading and Downloading Files
  3. Accessing Endpoints to Manage Files in Object Storage

Accessing Endpoints to Manage Files in Object Storage

A Public Wrapper API over the Object Storage that has a built-in virus scanning ability is been available to perform various actions on Object Storage.

The following terms are used in Table 3-1:

  • PAR: a pre-authenticated request used to upload or download files. This is valid only for a limited duration and is set to five minutes.

  • Storage Prefix: Object Storage is a flat storage area and does not include the concept of directories. Storage prefix is a prefix for a file that imitates a directory structure.

    For example, planning/incoming is prefixed to a filename to provide a more readable and distinguishable name.

Before accessing the APIs, an OCI IAM token must be generated. This token is passed in the request header for authentication.

curl -i -u "<IDCS-client-id>":"<IDCS-client-secret>" \
https://<idcs-tenant-id>.<IDCS_URL> \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Host: <idcs-tenant-id>.<IDCS_URL>' \
-d 'grant_type=client_credentials' -d 'scope=urn:opc:idm:__myscopes__'

Table 3-1 API Endpoints

Action Endpoint Payload Response Details

Get PAR (pre-authenticated requests) for upload of files

/uploadFiles

 
[ {
    "storagePrefix": "string",
    "fileName": "string"
},
...]

PAR URI

This endpoint is used to generate PARs, which are then used to upload files.

Data:

{
    "listOfFiles": [{
        "storagePrefix": "<subnamespace>/planning/incoming/input",
        "fileName": "prod.csv.dat"
    },
    {
        "storagePrefix": "<subnamespace>/planning/incoming/config",
        "fileName": "RetailHomeConfig.json"
    }]
}

Command:

curl -X POST "<url>/<BucketName>/uploadFiles" \
 
-H "accept: application/json" -H "Accept-Language: en" -H "Authorization: Bearer <AccessToken>" -H "Content-Type: application/json" \
 
-d "{\"listOfFiles\":[{\"storagePrefix\":\"<subnamespace>/planning/incoming/input\",\"fileName\":\"prod.csv.dat\"},{\"storagePrefix\":\" \<subnamespace>/planning/incoming/config/\",\"fileName\":\"RetailHomeConfig.json\"}]}"

Response 200:

{
    "parList": [{
        "id": "WhmJ1Jn6v1GufaHDVISg2sUyiOLEoDAG3rWGUp1J/yj7NgvpJtf77q6Qehsz9h9R:<subnamespace>/planning/incoming/input/prod.csv.dat",
        "name": "prod.csv.dat",
        "accessUri": "https://objectstorage.us-phoenix-1.oraclecloud.com/p/oKDbsdO0T3LsfEWgys5WMD85DOyB7W4AvNK_lYXGtVMkGobebU6NIdvuz5AqrtO4/n/oraclegbudevcorp/b/<BucketName>/o/<subnamespace>/planning/incoming/input/prod.csv.dat",
        "objectName": "<subnamespace>/planning/incoming/input/prod.csv.dat",
        "accessType": "ObjectWrite",
        "timeExpires": 1629914865691,
        "timeCreated": 1629914565988
    },
    {
        "id": "I0zDNVNqpQG8KEgGoJokViRIZ6yAQNX7haWIvBfDME+UabAShOhVu7zNvmERkZLm:<subnamespace>/planning/incoming/config/RetailHomeConfig.json",
        "name": "RetailHomeConfig.json",
        "accessUri": "https://objectstorage.us-phoenix-1.oraclecloud.com/p/Oja49u66xQqkzgOC6i5GA1PooED1XQV2bsnDwurqKbwetAnqX1RzVb4-e1mPiWWs/n/oraclegbudevcorp/b/<BucketName>/o/<subnamespace>/planning/incoming/config/RetailHomeConfig.json",
        "objectName": "<subnamespace>/planning/incoming/config/RetailHomeConfig.json",
        "accessType": "ObjectWrite",
        "timeExpires": 1629914866213,
        "timeCreated": 1629914566301
    }]
}

Files can then be uploaded using the generated PARs (accessURI in the response).

curl --request PUT --data-binary <File> <PAR>

Get PAR for download of files

/downloadFiles

 
[ {
    "storagePrefix": "string",
    "fileName": "string"
},
...]

PAR URI

This endpoint is used to generate PARs, which are then used to download files.

Data:

{
    "listOfFiles": [{
        "storagePrefix": "<subnamespace>/planning/incoming/input",
        "fileName": "prod.csv.dat"
    },
    {
        "storagePrefix": "<subnamespace>/planning/incoming/config/",
        "fileName": "RetailHomeConfig.json"
    }]
}

Command:

curl -X POST "<url>/<BucketName>/downloadFiles" \
-H "accept: application/json" -H "Accept-Language: en" -H "Authorization: Bearer <AccessToken>" -H "Content-Type: application/json" \
-d "{\"listOfFiles\":[{\"storagePrefix\":\"<subnamespace>/planning/incoming/input\",\"fileName\":\"prod.csv.dat\"},{\"storagePrefix\":\" \<subnamespace>/planning/incoming/config/\",\"fileName\":\"RetailHomeConfig.json\"}]}"

Response 200:

{
    "parList": [{
        "id": "SMINYf9O09IQmfkIxb8gHb0oRN2VrgAD88knbvo3pcNvvrNEhG8btWlPOdnfcLRG:<subnamespace>/planning/incoming/input/prod.csv.dat",
        "name": "prod.csv.dat",
        "accessUri": "https://objectstorage.us-phoenix-1.oraclecloud.com/p/M7JSr6Jp4up_XnVgib6xXqCuc17YHoWZDVzwGmt1x76_sqIRTQGHS3X_5aMar2HV/n/oraclegbudevcorp/b/<BucketName>/o/<subnamespace>/planning/incoming/input/prod.csv.dat",
        "objectName": "<subnamespace>/planning/incoming/input/prod.csv.dat",
        "accessType": "ObjectRead",
        "timeExpires": 1629916720360,
        "timeCreated": 1629916420483
    },
    {
        "id": "8Jtqp6T2g3k+1KY9RhO9D7Kftmm5OBn6PIhCzxIQAH9jbvyQmi54SNoXuEzx0eqM:<subnamespace>/planning/incoming/config/RetailHomeConfig.json",
        "name": "RetailHomeConfig.json",
        "accessUri": "https://objectstorage.us-phoenix-1.oraclecloud.com/p/5wvRsj2D00nRkjX7-IMZoo9xOSRkMJUM37yyy4wKL1PKwTpdgQ8BWQKlg_jHXnrh/n/oraclegbudevcorp/b/<BucketName>/o/<subnamespace>/planning/incoming/config/RetailHomeConfig.json",
        "objectName": "<subnamespace>/planning/incoming/config/RetailHomeConfig.json",
        "accessType": "ObjectRead",
        "timeExpires": 1629916720632,
        "timeCreated": 1629916420742
    }]
}

Files can then be downloaded using the generated PARs (accessURI in the response).

curl --request GET <PAR> --output <file>

Delete Files

/deleteFiles

 
[ {
    "storagePrefix": "string",
    "fileName": "string"
},
...]

Status: ok/error per file

This endpoint is used to delete files from Object Storage.

Data:

{
    "listOfFiles": [{
        "storagePrefix": "<subnamespace>/planning/incoming/input",
        "fileName": "prod.csv.dat"
    },
    {
        "storagePrefix": "<subnamespace>/planning/incoming/config/",
        "fileName": "RetailHomeConfig.json"
    }]
}

Command:

curl -X DELETE "<url>/<BucketName>/deleteFiles" \
-H "accept: */*" -H "Accept-Language: en" -H "Authorization: Bearer <AccessToken>" -H "Content-Type: application/json" \
-d "{\"listOfFiles\":[{\"storagePrefix\":\"<subnamespace>/planning/incoming/input\",\"fileName\":\"prod.csv.dat\"},{\"storagePrefix\":\"<subnamespace>/planning/incoming/config/\",\"fileName\":\"RetailHomeConfig.json\"}]}"

Response 200:

{
    "filesDeleted": [{
        "filePath": {
            "storagePrefix": "<subnamespace>/planning/incoming/input",
            "fileName": "prod.csv.dat"
        },
        "responseMessage": "File successfully deleted <subnamespace>/planning/incoming/input/prod.csv.dat"
    },
    {
        "filePath": {
            "storagePrefix": "<subnamespace>/planning/incoming/config/",
            "fileName": "RetailHomeConfig.json"
        },
        "responseMessage": "File successfully deleted <subnamespace>/planning/incoming/config/RetailHomeConfig.json"
    }],
    "filesFailedDeletion": []
}

Move/Rename Files

/moveFiles

 
[ {
       currentPath: {
        "storagePrefix": "string",
        "fileName": "string"
    },
       newPath: {
        "storagePrefix": "string",
        "fileName": "string"
    } 
},
...]

Status: ok/error per file

This endpoint is used to move files within Object Storage.

Data:

{
    "listOfFiles": [{
        "currentPath": {
            "storagePrefix": "<subnamespace>/planning/incoming/input2",
            "fileName": "prod.csv.dat"
        },
        "newPath": {
            "storagePrefix": "<subnamespace>/planning/incoming/config1/",
            "fileName": "prod.csv.dat"
        }
    }]
}

Command:

curl -X POST "<url>/<BucketName>/movefiles" \
-H "accept: */*" -H "Accept-Language: en" -H "Authorization: Bearer <AccessToken>" -H "Content-Type: application/json" \
-d "{\"listOfFiles\":[{\"currentPath\":{\"storagePrefix\":\"<subnamespace>/planning/incoming/input2\",\"fileName\":\"prod.csv.dat\"},\"newPath\":{\"storagePrefix\":\"<subnamespace>/planning/incoming/config1/\",\"fileName\":\"prod.csv.dat\"}}]}"

Response:

{
    "failedMove": [],
    "successfulMove": [{
        "moveFile": {
            "currentPath": {
                "storagePrefix": "<subnamespace>/planning/incoming/input2",
                "fileName": "prod.csv.dat"
            },
            "newPath": {
                "storagePrefix": "<subnamespace>/planning/incoming/config1/",
                "fileName": "prod.csv.dat"
            }
        },
        "responseMessage": "Successfully moved."
    }]
}

List storage prefixes

/listStoragePrefixes

 
{
    "storagePrefix": "string",
    "fileNameStartsWith": "optional_string"
}

Storage prefix name, Size, Number of files

This endpoint is used to list Storage Prefixes in Object Storage.

Allows customer to discover consumption and storage prefix names.

curl -X GET "<url>/<BucketName>/listprefixes" -H "accept: application/json" -H "Accept-Language: en" -H "Authorization: Bearer <AccessToken>"

Response: 200

[
"<subnamespace>/planning/incoming/config/",
"<subnamespace>/planning/incoming/input"
]

List files within a storage prefix

/listFiles

 
{
    "storagePrefix": "optional_string"
}

storage prefix name, file name, size, md5 checksum, created date, modified date, scan date, scan status

This endpoint is used to find and list files from Object Storage.

curl -X GET "<url>/<BucketName>/listfiles?prefix=<subnamespace>/planning/incoming&contains=prod&sort=size:asc" \
-H "accept: application/json" -H "Accept-Language: en" -H "Authorization: Bearer <AccessToken>"

Response:

{
    "resultSet": [{
        "name": "<subnamespace>/planning/incoming/config1/prod.csv.dat",
        "size": 177023,
        "md5": "vlN/r8gbNyQ1EdsC++Hv1w==",
        "version": "ca60582d-bacb-4309-bbbf-89d4a1aa2843",
        "etag": "7d6dde3b-5b5b-430d-8494-78e090418946",
        "createdDate": "2021-08-25T20:36:40Z",
        "modifiedDate": "2021-08-25T20:36:40Z",
        "scanStatus": "Passed"
    }],
    "totalResults": 1,
    "limit": 0,
    "count": 1,
    "offset": 0,
    "hasMore": false
}

Find file

/findFileByName

 
{
    "stringContains": "string"
}

storage prefix name, file name, size, md5 checksum, created date, modified date, scan date, scan status

This endpoint is used to find and list files from Object Storage.

curl -X GET "<url>/<BucketName>/findFileByName?prefix=<subnamespace>/planning/incoming&contains=prod&sort=size:asc" \
-H "accept: application/json" -H "Accept-Language: en" -H "Authorization: Bearer <AccessToken>"

Response:

{
    "resultSet": [{
        "name": "<subnamespace>/planning/incoming/config1/prod.csv.dat",
        "size": 177023,
        "md5": "vlN/r8gbNyQ1EdsC++Hv1w==",
        "version": "ca60582d-bacb-4309-bbbf-89d4a1aa2843",
        "etag": "7d6dde3b-5b5b-430d-8494-78e090418946",
        "createdDate": "2021-08-25T20:36:40Z",
        "modifiedDate": "2021-08-25T20:36:40Z",
        "scanStatus": "Passed"
    }],
    "totalResults": 1,
    "limit": 0,
    "count": 1,
    "offset": 0,
    "hasMore": false
}

Liveness test

/ping

This endpoint allows customer to check for service liveness.

curl -X GET "<url>/ping" -H "accept: */*" -H "Accept-Language: en" -H "Authorization: Bearer <AccessToken>"

Response:

{
"appStatus": 200
}