Package video.api.client.api

Class ApiClient

  • public class ApiClient
extends Object

    • Constructor Detail

      • ApiClient

        public ApiClient​(String basePath)

      • ApiClient

        public ApiClient​(String apiKey,
                 String basePath)
        Constructor for ApiClient with custom API base path
        Parameters:
        apiKey - the api key to use to authenticate to the API
        basePath - the api base path. Can in particular be ApiClient.BasePaths.PRODUCTION (default) or ApiClient.BasePaths.SANDBOX

      • ApiClient

        public ApiClient​(okhttp3.OkHttpClient client,
                 String basePath)
        Constructor for ApiClient with custom http client
        Parameters:
        client - an OkHttpClient instance used to make API call

    • Method Detail

      • getBasePath

        public String getBasePath()
        Get base path
        Returns:
        Base path

      • setBasePath

        public void setBasePath​(String basePath)
        Set base path

      • getHttpClient

        public okhttp3.OkHttpClient getHttpClient()
        Get HTTP client
        Returns:
        An instance of OkHttpClient

      • getJSON

        public JSON getJSON()
        Get JSON
        Returns:
        JSON object

      • setJSON

        public ApiClient setJSON​(JSON json)
        Set JSON
        Parameters:
        json - JSON object
        Returns:
        Api client

      • isVerifyingSsl

        public boolean isVerifyingSsl()
        True if isVerifyingSsl flag is on
        Returns:
        True if isVerifySsl flag is on

      • setVerifyingSsl

        public ApiClient setVerifyingSsl​(boolean verifyingSsl)
        Configure whether to verify certificate and hostname when making https requests. Default to true. NOTE: Do NOT set to false in production code, otherwise you would face multiple types of cryptographic attacks.
        Parameters:
        verifyingSsl - True to verify TLS/SSL connection
        Returns:
        ApiClient

      • getSslCaCert

        public InputStream getSslCaCert()
        Get SSL CA cert.
        Returns:
        Input stream to the SSL CA cert

      • setSslCaCert

        public ApiClient setSslCaCert​(InputStream sslCaCert)
        Configure the CA certificate to be trusted when making https requests. Use null to reset to default.
        Parameters:
        sslCaCert - input stream for SSL CA cert
        Returns:
        ApiClient

      • getKeyManagers

        public KeyManager[] getKeyManagers()

      • setKeyManagers

        public ApiClient setKeyManagers​(KeyManager[] managers)
        Configure client keys to use for authorization in an SSL session. Use null to reset to default.
        Parameters:
        managers - The KeyManagers to use
        Returns:
        ApiClient

      • addDefaultHeader

        public ApiClient addDefaultHeader​(String key,
                                  String value)
        Add a default header.
        Parameters:
        key - The header's key
        value - The header's value
        Returns:
        ApiClient

      • addDefaultCookie

        public ApiClient addDefaultCookie​(String key,
                                  String value)
        Add a default cookie.
        Parameters:
        key - The cookie's key
        value - The cookie's value
        Returns:
        ApiClient

      • isDebugging

        public boolean isDebugging()
        Check that whether debugging is enabled for this API client.
        Returns:
        True if debugging is enabled, false otherwise.

      • setDebugging

        public ApiClient setDebugging​(boolean debugging)
        Enable/disable debugging for this API client.
        Parameters:
        debugging - To enable (true) or disable (false) debugging
        Returns:
        ApiClient

      • getConnectTimeout

        public int getConnectTimeout()
        Get connection timeout (in milliseconds).
        Returns:
        Timeout in milliseconds

      • setConnectTimeout

        public ApiClient setConnectTimeout​(int connectionTimeout)
        Sets the connect timeout (in milliseconds). A value of 0 means no timeout, otherwise values must be between 1 and Integer.MAX_VALUE.
        Parameters:
        connectionTimeout - connection timeout in milliseconds
        Returns:
        Api client

      • getReadTimeout

        public int getReadTimeout()
        Get read timeout (in milliseconds).
        Returns:
        Timeout in milliseconds

      • setReadTimeout

        public ApiClient setReadTimeout​(int readTimeout)
        Sets the read timeout (in milliseconds). A value of 0 means no timeout, otherwise values must be between 1 and Integer.MAX_VALUE.
        Parameters:
        readTimeout - read timeout in milliseconds
        Returns:
        Api client

      • getWriteTimeout

        public int getWriteTimeout()
        Get write timeout (in milliseconds).
        Returns:
        Timeout in milliseconds

      • setWriteTimeout

        public ApiClient setWriteTimeout​(int writeTimeout)
        Sets the write timeout (in milliseconds). A value of 0 means no timeout, otherwise values must be between 1 and Integer.MAX_VALUE.
        Parameters:
        writeTimeout - connection timeout in milliseconds
        Returns:
        Api client

      • parameterToPair

        public List<Pair> parameterToPair​(String name,
                                  Object value)
        Formats the specified query parameter to a list containing a single Pair object. Note that value must not be a collection.
        Parameters:
        name - The name of the parameter.
        value - The value of the parameter.
        Returns:
        A list containing a single Pair object.

      • parameterToPairs

        public List<Pair> parameterToPairs​(String collectionFormat,
                                   String name,
                                   Collection value)
        Formats the specified collection query parameters to a list of Pair objects. Note that the values of each of the returned Pair objects are percent-encoded.
        Parameters:
        collectionFormat - The collection format of the parameter.
        name - The name of the parameter.
        value - The value of the parameter.
        Returns:
        A list of Pair objects.

      • collectionPathParameterToString

        public String collectionPathParameterToString​(String collectionFormat,
                                              Collection value)
        Formats the specified collection path parameter to a string value.
        Parameters:
        collectionFormat - The collection format of the parameter.
        value - The value of the parameter.
        Returns:
        String representation of the parameter

      • sanitizeFilename

        public String sanitizeFilename​(String filename)
        Sanitize filename by removing path. e.g. ../../sun.gif becomes sun.gif
        Parameters:
        filename - The filename to be sanitized
        Returns:
        The sanitized filename

      • isJsonMime

        public boolean isJsonMime​(String mime)
        Check if the given MIME is a JSON MIME. JSON MIME examples: application/json application/json; charset=UTF8 APPLICATION/JSON application/vnd.company+json "* / *" is also default to JSON
        Parameters:
        mime - MIME (Multipurpose Internet Mail Extensions)
        Returns:
        True if the given MIME is JSON, false otherwise.

      • selectHeaderAccept

        public String selectHeaderAccept​(String[] accepts)
        Select the Accept header's value from the given accepts array: if JSON exists in the given array, use it; otherwise use all of them (joining into a string)
        Parameters:
        accepts - The accepts array to select from
        Returns:
        The Accept header to use. If the given array is empty, null will be returned (not to set the Accept header explicitly).

      • selectHeaderContentType

        public String selectHeaderContentType​(String[] contentTypes)
        Select the Content-Type header's value from the given array: if JSON exists in the given array, use it; otherwise use the first one of the array.
        Parameters:
        contentTypes - The Content-Type array to select from
        Returns:
        The Content-Type header to use. If the given array is empty, or matches "any", JSON will be used.

      • escapeString

        public String escapeString​(String str)
        Escape the given string to be used as URL query value.
        Parameters:
        str - String to be escaped
        Returns:
        Escaped string

      • deserialize

        public <T> T deserialize​(okhttp3.Response response,
                         Type returnType)
                  throws ApiException
        Deserialize response body to Java object, according to the return type and the Content-Type response header.
        Type Parameters:
        T - Type
        Parameters:
        response - HTTP response
        returnType - The type of the Java object
        Returns:
        The deserialized Java object
        Throws:
        ApiException - If fail to deserialize response body, i.e. cannot read response body or the Content-Type of the response is not supported.

      • serialize

        public okhttp3.RequestBody serialize​(Object obj,
                                     String contentType)
                              throws ApiException
        Serialize the given Java object into request body according to the object's class and the request Content-Type.
        Parameters:
        obj - The Java object
        contentType - The request Content-Type
        Returns:
        The serialized request body
        Throws:
        ApiException - If fail to serialize the given object

      • downloadFileFromResponse

        public File downloadFileFromResponse​(okhttp3.Response response)
                              throws ApiException
        Download file from the given response.
        Parameters:
        response - An instance of the Response object
        Returns:
        Downloaded file
        Throws:
        ApiException - If fail to read file content from response and write to disk

      • prepareDownloadFile

        public File prepareDownloadFile​(okhttp3.Response response)
                         throws IOException
        Prepare file for download
        Parameters:
        response - An instance of the Response object
        Returns:
        Prepared file for the download
        Throws:
        IOException - If fail to prepare file for download

      • execute

        public <T> ApiResponse<T> execute​(okhttp3.Call call,
                                  Type returnType)
                           throws ApiException
        Execute HTTP call and deserialize the HTTP response body into the given return type.
        Type Parameters:
        T - The return type corresponding to (same with) returnType
        Parameters:
        returnType - The return type used to deserialize HTTP response body
        call - Call
        Returns:
        ApiResponse object containing response status, headers and data, which is a Java object deserialized from response body and would be null when returnType is null.
        Throws:
        ApiException - If fail to execute the call

      • executeAsync

        public <T> void executeAsync​(okhttp3.Call call,
                             Type returnType,
                             ApiCallback<T> callback)
        Execute HTTP call asynchronously.
        Type Parameters:
        T - Type
        Parameters:
        call - The callback to be executed when the API call finishes
        returnType - Return type
        callback - ApiCallback
        See Also:
        execute(Call, Type)

      • handleResponse

        public <T> T handleResponse​(okhttp3.Response response,
                            Type returnType)
                     throws ApiException
        Handle the given response, return the deserialized object when the response is successful.
        Type Parameters:
        T - Type
        Parameters:
        response - Response
        returnType - Return type
        Returns:
        Type
        Throws:
        ApiException - If the response has an unsuccessful status code or fail to deserialize the response body

      • buildCall

        public okhttp3.Call buildCall​(String path,
                              String method,
                              List<Pair> queryParams,
                              List<Pair> collectionQueryParams,
                              Object body,
                              Map<String,​String> headerParams,
                              Map<String,​String> cookieParams,
                              Map<String,​Object> formParams,
                              String[] authNames,
                              ApiCallback callback)
                       throws ApiException
        Build HTTP call with the given options.
        Parameters:
        path - The sub-path of the HTTP URL
        method - The request method, one of "GET", "HEAD", "OPTIONS", "POST", "PUT", "PATCH" and "DELETE"
        queryParams - The query parameters
        collectionQueryParams - The collection query parameters
        body - The request body object
        headerParams - The header parameters
        cookieParams - The cookie parameters
        formParams - The form parameters
        authNames - The authentications to apply
        callback - Callback for upload/download progress
        Returns:
        The HTTP call
        Throws:
        ApiException - If fail to serialize the request body object

      • buildRequest

        public okhttp3.Request buildRequest​(String path,
                                    String method,
                                    List<Pair> queryParams,
                                    List<Pair> collectionQueryParams,
                                    Object body,
                                    Map<String,​String> headerParams,
                                    Map<String,​String> cookieParams,
                                    Map<String,​Object> formParams,
                                    String[] authNames,
                                    ApiCallback callback)
                             throws ApiException
        Build an HTTP request with the given options.
        Parameters:
        path - The sub-path of the HTTP URL
        method - The request method, one of "GET", "HEAD", "OPTIONS", "POST", "PUT", "PATCH" and "DELETE"
        queryParams - The query parameters
        collectionQueryParams - The collection query parameters
        body - The request body object
        headerParams - The header parameters
        cookieParams - The cookie parameters
        formParams - The form parameters
        authNames - The authentications to apply
        callback - Callback for upload/download progress
        Returns:
        The HTTP request
        Throws:
        ApiException - If fail to serialize the request body object

      • buildUrl

        public String buildUrl​(String path,
                       List<Pair> queryParams,
                       List<Pair> collectionQueryParams)
        Build full URL by concatenating base path, the given sub path and query parameters.
        Parameters:
        path - The sub path
        queryParams - The query parameters
        collectionQueryParams - The collection query parameters
        Returns:
        The full URL

      • processHeaderParams

        public void processHeaderParams​(Map<String,​String> headerParams,
                                okhttp3.Request.Builder reqBuilder)
        Set header parameters to the request builder, including default headers.
        Parameters:
        headerParams - Header parameters in the form of Map
        reqBuilder - Request.Builder

      • processCookieParams

        public void processCookieParams​(Map<String,​String> cookieParams,
                                okhttp3.Request.Builder reqBuilder)
        Set cookie parameters to the request builder, including default cookies.
        Parameters:
        cookieParams - Cookie parameters in the form of Map
        reqBuilder - Request.Builder

      • buildRequestBodyFormEncoding

        public okhttp3.RequestBody buildRequestBodyFormEncoding​(Map<String,​Object> formParams)
        Build a form-encoding request body with the given form parameters.
        Parameters:
        formParams - Form parameters in the form of Map
        Returns:
        RequestBody

      • buildRequestBodyMultipart

        public okhttp3.RequestBody buildRequestBodyMultipart​(Map<String,​Object> formParams)
        Build a multipart (file uploading) request body with the given form parameters, which could contain text fields and file fields.
        Parameters:
        formParams - Form parameters in the form of Map
        Returns:
        RequestBody

      • guessContentTypeFromFile

        public String guessContentTypeFromFile​(File file)
        Guess Content-Type header from the given file (defaults to "application/octet-stream").
        Parameters:
        file - The given file
        Returns:
        The guessed Content-Type

      • getUploadChunkSize

        public long getUploadChunkSize()

      • setUploadChunkSize

        public void setUploadChunkSize​(long uploadChunkSize)