dev-notes/docs/languages/python/libs/requests.md

Requests Lib

GET REQUEST

Get or retrieve data from specified resource

response = requests.get('URL')    # returns response object

# PAYLOAD -> valuable information of response
response.status_code    # http status code

The response message consists of:

• status line which includes the status code and reason message
• response header fields (e.g., Content-Type: text/html)
• empty line
• optional message body

1xx -> INFORMATIONAL RESPONSE
2xx -> SUCCESS
    200 OK -> request successful
3xx -> REDIRECTION
4xx -> CLIENT ERRORS
    404 NOT FOUND -> resource not found
5xx -> SERVER ERRORS

# raise exception HTTPError for error status codes
response.raise_for_status()

response.content    # raw bytes of payload
response.encoding = 'utf-8'    # specify encoding
response.text    # string payload (serialized JSON)
response.json()    # dict of payload
response.headers    # response headers (dict)

QUERY STRING PARAMETERS

response = requests.get('URL', params={'q':'query'})
response = requests.get('URL', params=[('q', 'query')])
response = requests.get('URL', params=b'q=query')

REQUEST HEADERS

response = requests.get(
    'URL',
    params={'q': 'query'},
    headers={'header': 'header_query'}
)

OTHER HTTP METHODS

DATA INPUT

# requests that entity enclosed be stored as a new subordinate of the web resource identified by the URI
requests.post('URL', data={'key':'value'})
# requests that the enclosed entity be stored under the supplied URI
requests.put('URL', data={'key':'value'})
# applies partial modification
requests.patch('URL', data={'key':'value'})
# deletes specified resource
requests.delete('URL')
# ask for a response but without the response body (only headers)
requests.head('URL')
# returns supported HTTP methods of the server
requests.options('URL')

SENDING JSON DATA

requests.post('URL', json={'key': 'value'})

INSPECTING THE REQUEST

# requests lib prepares the requests before sending it
response = requests.post('URL', data={'key':'value'})
response.request.something    # inspect request field

AUTHENTICATION

requests.get('URL', auth=('username', 'password'))    # use implicit HTTP Basic Authorization

# explicit HTTP Basic Authorization and other
from requests.auth import HTTPBasicAuth, HTTPDigestAuth, HTTPProxyAuth
from getpass import getpass
requests.get('URL', auth=HTTPBasicAuth('username', getpass()))

PERSONALIZED AUTH

from requests.auth import AuthBase
class TokenAuth(AuthBase):
    "custom authentication scheme"

    def __init__(self, token):
        self.token = token

    def __call__(self, r):
        """Attach API token to custom auth"""
        r.headers['X-TokenAuth'] = f'{self.token}'
        return r

requests.get('URL', auth=TokenAuth('1234abcde-token'))

DISABLING SSL VERIFICATION

requests.get('URL', verify=False)

PERFORMANCE

REQUEST TIMEOUT

# raise Timeout exception if request times out
requests.get('URL', timeout=(connection_timeout, read_timeout))

MAX RETRIES

from requests.adapters import HTTPAdapter
URL_adapter = HTTPAdapter(max_retries = int)
session = requests.Session()

# use URL_adapter for all requests to URL
session.mount('URL', URL_adapter)