Python Requests is a library that simplifies consuming RESTful resources from the client side. The Oracle Documents Cloud Service (DOCS) REST API fits well with Python Requests, allowing a service call to get a folder or file to be done in few lines of code. Since Python is naturally friendly to JSON responses, parsing the Response object can be done using standard syntax.

The Requests library must be installed to Python using the pip utility (or easy-install on Windows). The example below also uses the “getpass” module to handle user entry of a password.
Python Requests link: http://docs.python-requests.org/en/latest/

Python getpass module link: https://docs.python.org/2/library/getpass.html

A first look at using Requests with DOCS REST services is to get a user’s Personal Workspace. Notice that importing the Requests library allows calling a HTTP GET on a REST URL. All of the HTTP work is done in Python Requests and the client code need only pass in a URL, username, and password.
# Get password from user entry. This is using a module called "getpass" pw = getpass.getpass("Enter password:")
response = requests.get(docsurl, auth=(username, pw))
# View the status code - should be 200. Error handling can be done with the status code.
print (response.status_code)
# Header data is available from the Response object, which is part of Python Requests
print (response.headers['content-type'])

# Get the JSON data
j = response.json()
# Navigate the JSON data using standard Python
print('count=' + j['count'])
print('errorCode=' + j['errorCode'])
print('totalResults=' + j['totalResults'])

print('Items:')
for item in j['items']:
print ('type=' + item['type'] + ' name=' + item['name'] + ' owner=' + item['ownedBy']['displayName'])

An upload example requires a multipart HTTP POST request to send the file payload and a JSON payload. This example also shows the use of a Session in Python Requests. The Session can have the Authorization header set once and be re-used for all subsequent REST calls to Oracle Documents Cloud service. The example below uploads all files in a directory to a user’s DOCS account. A folder GUID is needed for the upload to add the new files into the target folder. Some additional lines of code are added here for printing out the amount of milliseconds that each upload takes. The upload request differs from the previous example in that the POST request needs multipart payload to succeed. Notice that a data part called “jsonInputParameters” and a file part called “primaryFile” are both added to the request. Python’s os module can handle opening the file and placing it into the multipart. A loop can grab each file from the directory and submit an upload request.
import os
import getpass
import time
import requests

docsurl='https://mydocsinstance/documents/api/1.1'
path = 'C:/TEMP/upload'
username = 'peter.flies@oracle.com'
uploadfolderid = 'F26415F66B0BE6EE53314461T0000DEFAULT00000000'

# Get user input to set the password. Set the REST client authorization header by directly passing in the username and password
pw = getpass.getpass("Enter password:")

files = (file for file in os.listdir(path)
if os.path.isfile(os.path.join(path, file)))

# Requests has a reusable Session object. Init it with the Authorization header
s = requests.Session()
s.auth = (username, pw)

print('Uploading files from path ' + path + ' to Documents Cloud Service ' + docsurl + '.\n')
for file in files:
startMillis = int(round(time.time() * 1000))
print('Uploading ' + file + '...')
print(path + '/' + file)
resourcePath = 'files/data'
fullpath = path + '/' + file
files = {
'primaryFile': open(fullpath, 'rb')
}
jsondata='{\"parentID\": \"' + uploadfolderid + '\" }'
data = {
'jsonInputParameters': jsondata
}
response = s.post(docsurl + '/' + resourcePath, files=files, data=data)
endMillis = int(round(time.time() * 1000))
if(response.status_code == 200 or response.status_code == 201):
j = response.json()
print('Upload successful. ' + str(endMillis - startMillis) + ' ms. File id: ' + j['id'] + ', version number: ' + j['version'] + '\n')
else:
print('ERROR: Upload unsuccessful for file: ' + file)
print(str(response.status_code) + ' ' + response.reason )
if(response.json()):
j = response.json()
print('Error details: ' + j['errorCode'] + ' ' + j['errorMessage'])
else:
print('Dump of response text:')
print(response.text + '\n')

A file download is a HTTP GET but requires saving the file to a location on disk. Again, Python has utilities to simplify the downloading and saving of Oracle Documents Cloud files.
import getpass
import requests
import logging

docsurl='https://documents.us.oracle.com/documents/api/1.1'
savePath = 'C:/TEMP/download'
username = 'peter.flies@oracle.com'
fileid = 'DCA4BBA0908AE2F497832BC2T0000DEFAULT00000000'
resourcePath = 'files/{fileid}/data'
resourcePath = resourcePath.replace('{fileid}', fileid)

# Get user input to set the password. Set the REST client authorization header
by directly passing in the username and password
pw = getpass.getpass("Enter password:")

# Requests has a reusable Session object. Init it with the Authorization header
s = requests.Session()
s.auth = (username, pw)

with open(savePath, 'wb') as fhandle:
response = s.get(docsurl + '/' + resourcePath, stream=True)

if not response.ok:
print("Error!") #What do you want to do in case of error?

for filePiece in response.iter_content(1024):
if not filePiece:
break

fhandle.write(filePiece)
#no JSON in response, but check it for status code, headers, etc.
print(response.status_code)


For services that you may want to call frequently, a Python class can be created that wraps the Requests library. The commonly used service calls and associated parameters can have a method signature that sets the default parameters, but can also be overridden as needed. In the example class file below, the “DOCSClient” class has a constructor that initializes the Session. Once a handle to a DOCSClient is created, a method called “itemPersonalWorkspace” can be called with parameters to set the sort order, limit, and offset. This sample class has methods for only a few of the Documents Cloud Service REST calls, but the example can be applied to any DOCS REST API.

Full article...