## Rest Client Usage

updated: December 08, 2017

# Rest Client Usage

## The rest_client module

class `ResponseBody`(response, body=None)

  Class that wraps an http response and dict body into a single value.

  Callers that receive this object will normally use it as a dict but can extract the response if needed.

class `ResponseBodyData`(response, data)

  Class that wraps an http response and string data into a single value.

class `ResponseBodyList`(response, body=None)

  Class that wraps an http response and list body into a single value.

  Callers that receive this object will normally use it as a list but can extract the response if needed.

class `RestClient`(auth_provider, service, region, endpoint_type='publicURL', build_interval=1, build_timeout=60, disable_ssl_certificate_validation=False, ca_certs=None, trace_requests='', name=None, http_timeout=None, proxy_url=None)

  Unified OpenStack RestClient class

  This class is used for building openstack api clients on top of. It is intended to provide a base layer for wrapping outgoing http requests in keystone auth as well as providing response code checking and error handling.

  Parameters:

  - auth_provider – an auth provider object used to wrap requests in auth
  - service (str) – The service name to use for the catalog lookup
  - region (str) – The region to use for the catalog lookup
  - name (str) – The endpoint name to use for the catalog lookup; this returns only if the service exists
  - endpoint_type (str) – The endpoint type to use for the catalog lookup
  - build_interval (int) – Time in seconds between to status checks in wait loops
  - build_timeout (int) – Timeout in seconds to wait for a wait operation.
  - disable_ssl_certificate_validation (bool) – Set to true to disable ssl certificate validation
  - ca_certs (str) – File containing the CA Bundle to use in verifying a TLS server cert
  - trace_requests (str) – Regex to use for specifying logging the entirety of the request and response payload
  - http_timeout (str) – Timeout in seconds to wait for the http request to return
  - proxy_url (str) – http proxy url to use.

  `copy`(url, headers=None, extra_headers=False)

    Send a HTTP COPY request using keystone service catalog and auth

    Parameters:

    - url (str) – the relative url to send the post request to
    - headers (dict) – The headers to use for the request
    - extra_headers (bool) – Boolean value than indicates if the headers returned by the get_headers() method are to be used but additional headers are needed in the request pass them in as a dict.

    Returns: | a tuple with the first entry containing the response headers and the second the response body
    Return type: | tuple

  `delete`(url, headers=None, body=None, extra_headers=False)

    Send a HTTP DELETE request using keystone service catalog and auth

    Parameters:

    - url (str) – the relative url to send the post request to
    - headers (dict) – The headers to use for the request
    - body (dict) – the request body
    - extra_headers (bool) – Boolean value than indicates if the headers returned by the get_headers() method are to be used but additional headers are needed in the request pass them in as a dict.

    Returns: | a tuple with the first entry containing the response headers and the second the response body
    Return type: | tuple

  classmethod `expected_success`(expected_code, read_code)

    Check expected success response code against the http response

    Parameters:

    - expected_code (int) – The response code that is expected. Optionally a list of integers can be used to specify multiple valid success codes
    - read_code (int) – The response code which was returned in the response

    Raises:

    - AssertionError – if the expected_code isn’t a valid http success response code
    - exceptions.InvalidHttpSuccessCode – if the read code isn’t an expected http success code

  `get`(url, headers=None, extra_headers=False)

    Send a HTTP GET request using keystone service catalog and auth

    Parameters:

    - url (str) – the relative url to send the post request to
    - headers (dict) – The headers to use for the request
    - extra_headers (bool) – Boolean value than indicates if the headers returned by the get_headers() method are to be used but additional headers are needed in the request pass them in as a dict.

    Returns: | a tuple with the first entry containing the response headers and the second the response body
    Return type: | tuple

  `get_headers`(accept_type=None, send_type=None)

    Return the default headers which will be used with outgoing requests

    Parameters:

    - accept_type (str) – The media type to use for the Accept header, if one isn’t provided the object var TYPE will be used
    - send_type (str) – The media-type to use for the Content-Type header, if one isn’t provided the object var TYPE will be used

    Return type: | dict
    Returns: | The dictionary of headers which can be used in the headers dict for outgoing request

  `get_versions`()

    Get the versions on a endpoint from the keystone catalog

    This method will make a GET request on the baseurl from the keystone catalog to return a list of API versions. It is expected that a GET on the endpoint in the catalog will return a list of supported API versions.

    Returns: | tuple with response headers and list of version numbers
    Return type: | tuple

  `head`(url, headers=None, extra_headers=False)

    Send a HTTP HEAD request using keystone service catalog and auth

    Parameters:

    - url (str) – the relative url to send the post request to
    - headers (dict) – The headers to use for the request
    - extra_headers (bool) – Boolean value than indicates if the headers returned by the get_headers() method are to be used but additional headers are needed in the request pass them in as a dict.

    Returns: | a tuple with the first entry containing the response headers and the second the response body
    Return type: | tuple

  `is_resource_deleted`(id)

    Subclasses override with specific deletion detection.

  `password`

    The password being used for requests

    Return type: | string
    Returns: | The password being used for requests

  `patch`(url, body, headers=None, extra_headers=False)

    Send a HTTP PATCH request using keystone service catalog and auth

    Parameters:

    - url (str) – the relative url to send the post request to
    - body (dict) – the request body
    - headers (dict) – The headers to use for the request
    - extra_headers (bool) – Boolean value than indicates if the headers returned by the get_headers() method are to be used but additional headers are needed in the request pass them in as a dict.

    Returns: | a tuple with the first entry containing the response headers and the second the response body
    Return type: | tuple

  `post`(url, body, headers=None, extra_headers=False, chunked=False)

    Send a HTTP POST request using keystone auth

    Parameters:

    - url (str) – the relative url to send the post request to
    - body (dict) – the request body
    - headers (dict) – The headers to use for the request
    - extra_headers (bool) – Boolean value than indicates if the headers returned by the get_headers() method are to be used but additional headers are needed in the request pass them in as a dict.
    - chunked (bool) – sends the body with chunked encoding

    Returns: | a tuple with the first entry containing the response headers and the second the response body
    Return type: | tuple

  `put`(url, body, headers=None, extra_headers=False, chunked=False)

    Send a HTTP PUT request using keystone service catalog and auth

    Parameters:

    - url (str) – the relative url to send the post request to
    - body (dict) – the request body
    - headers (dict) – The headers to use for the request
    - extra_headers (bool) – Boolean value than indicates if the headers returned by the get_headers() method are to be used but additional headers are needed in the request pass them in as a dict.
    - chunked (bool) – sends the body with chunked encoding

    Returns: | a tuple with the first entry containing the response headers and the second the response body
    Return type: | tuple

  `raw_request`(url, method, headers=None, body=None, chunked=False)

    Send a raw HTTP request without the keystone catalog or auth

    This method sends a HTTP request in the same manner as the request() method, however it does so without using keystone auth or the catalog to determine the base url. Additionally no response handling is done the results from the request are just returned.

    Parameters:

    - url (str) – Full url to send the request
    - method (str) – The HTTP verb to use for the request
    - headers (str) – Headers to use for the request if none are specifed the headers
    - body (str) – Body to send with the request
    - chunked (bool) – sends the body with chunked encoding

    Return type: | tuple
    Returns: | a tuple with the first entry containing the response headers and the second the response body

  `request`(method, url, extra_headers=False, headers=None, body=None, chunked=False)

    Send a HTTP request with keystone auth and using the catalog

    This method will send an HTTP request using keystone auth in the headers and the catalog to determine the endpoint to use for the baseurl to send the request to. Additionally

    When a response is received it will check it to see if an error response was received. If it was an exception will be raised to enable it to be handled quickly.

    This method will also handle rate-limiting, if a 413 response code is received it will retry the request after waiting the ‘retry-after’ duration from the header.

    Parameters:

    - method (str) – The HTTP verb to use for the request
    - url (str) – Relative url to send the request to
    - extra_headers (bool) – Boolean value than indicates if the headers returned by the get_headers() method are to be used but additional headers are needed in the request pass them in as a dict.
    - headers (dict) – Headers to use for the request if none are specifed the headers returned from the get_headers() method are used. If the request explicitly requires no headers use an empty dict.
    - body (str) – Body to send with the request
    - chunked (bool) – sends the body with chunked encoding

    Return type: | tuple
    Returns: | a tuple with the first entry containing the response headers and the second the response body

    Raises:

    - UnexpectedContentType – If the content-type of the response isn’t an expect type
    - Unauthorized – If a 401 response code is received
    - Forbidden – If a 403 response code is received
    - NotFound – If a 404 response code is received
    - BadRequest – If a 400 response code is received
    - Gone – If a 410 response code is received
    - Conflict – If a 409 response code is received
    - PreconditionFailed – If a 412 response code is received
    - OverLimit – If a 413 response code is received and over_limit is not in the response body
    - RateLimitExceeded – If a 413 response code is received and over_limit is in the response body
    - InvalidContentType – If a 415 response code is received
    - UnprocessableEntity – If a 422 response code is received
    - InvalidHTTPResponseBody – The response body wasn’t valid JSON and couldn’t be parsed
    - NotImplemented – If a 501 response code is received
    - ServerFault – If a 500 response code is received
    - UnexpectedResponseCode – If a response code above 400 is received and it doesn’t fall into any of the handled checks

  `reset_path`()

    When reset, use the base URL from the catalog as-is

  `resource_type`

    Returns the primary type of resource this client works with.

  `response_checker`(method, resp, resp_body)

    A sanity check on the response from a HTTP request

    This method does a sanity check on whether the response from an HTTP request conforms the HTTP RFC.

    Parameters:

    - method (str) – The HTTP verb of the request associated with the response being passed in.
    - resp – The response headers
    - resp_body – The body of the response

    Raises:

    - ResponseWithNonEmptyBody – If the response with the status code is not supposed to have a body
    - ResponseWithEntity – If the response code is 205 but has an entity

  `skip_path`()

    When set, ignore the path part of the base URL from the catalog

  `tenant_id`

    The tenant/project id being used for requests

    Return type: | string
    Returns: | The tenant/project id being used for requests

  `tenant_name`

    The tenant/project being used for requests

    Return type: | string
    Returns: | The tenant/project name being used for requests

  `user`

    The username used for requests

    Return type: | string
    Returns: | The username being used for requests

  `user_id`

    The user_id used for requests

    Return type: | string
    Returns: | The user id being used for requests

  `wait_for_resource_deletion`(id)

    Waits for a resource to be deleted

    This method will loop over is_resource_deleted until either is_resource_deleted returns True or the build timeout is reached. This depends on is_resource_deleted being implemented

    Parameters: | id (str) – The id of the resource to check
    Raises: | TimeoutException – If the build_timeout has elapsed and the resource still hasn’t been deleted

updated: December 08, 2017

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug questions?