Engee documentation

A class for working with HTTP on the user’s client program

Page in progress.

Hardware Support Package Engee provides the user with the ability to act as an HTTP client to communicate with external services via the REST API.

function close_session(device::HttpType)::Nothing

De-initialization of a previously created HTTP client.

Arguments

device::HttpType: an object of the HTTP.Http() type.

function delete(device::HttpType, endpoint::String, request_data::HTTPRequestData, headers::Dict{String, String}=Dict(), timeout::Union{Int64, Nothing}=nothing)::HTTPResponse

DELETE is a REST API request.

Arguments

  • device::HttpType: an object of the HTTP.Http() type.

  • endpoint::String: the endpoint for accessing an HTTP resource.

  • request_data::HTTPRequestData: an HTTPRequestData object. HTTPRequestData has a signature:

    Base.@kwdef struct HTTPRequestData
  params::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
  data::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
  json_data::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
  files::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
end

    Описание: Тело запроса (если включает в себя данные) и json-данные (если есть)

  • params: параметры

    • Тип: словарь или nothing (необязательный).

    • Назначение: параметры URL-строки запроса (то, что идет после ? в адресе). Пример: {"page": 1, "limit": 20, "sort": "name"} → ?page=1&limit;=20&sort;=name.

    • Поддерживаемые типы значений:

      • Числа (целые и дробные);

      • Строки;

      • Логические значения (true/false);

      • Бинарные данные (байты);

      • Списки примитивных типов; Вложенные словари.

  • data: данные

    • Тип: словарь или nothing (необязательный).

    • Назначение: данные для тела запроса в формате x-www-form-urlencoded.

    • Использование: для отправки форм обычных данных (не файлов). Пример: {"username": "john", "password": "secret"}

    • Поддерживаемые типы: такие же, как у params.

  • json_data: JSON-данные

    • Тип: словарь или nothing (необязательный).

    • Назначение: данные для тела запроса в формате JSON.

    • Использование: для REST API, где ожидается JSON. Пример: {"user": {"name": "John", "age": 30}}.

    • Особенность: автоматически сериализуется в JSON строку.

    • Поддерживаемые типы: такие же, как у params.

  • files: файлы

    • Тип: словарь или nothing (необязательный).

    • Назначение: данные для загрузки файлов (мультипарт-запросы).

    • Использование: для отправки файлов через формы. Пример: {"avatar": "binary_data", "document": "file_content"}.

    • Поддерживаемые типы: такие же, как у params, но обычно содержит бинарные данные.

    • Пример создания:

    julia-repl params = Dict("param1" => "value1", "param2" => "value2") request_data = HTTPRequestData(params=params, data=nothing, json_data=nothing, files=nothing)

  • headers: дополнительные заголовки. Например, настройка заголовков соединения и MIME-type запросов:

    headers = Dict{String, String}()
headers["connection"] = "keep-alive"
headers["Accept"] = "application/json"

  • timeout: таймаут на ожидание ответа в секундах. Возвращает HTTPResponse (объект типа HTTPResponse). Пример:

    Base.@kwdef struct HTTPResponse
text_content::Union{String, Nothing} = nothing
bytes_content::Union{Vector{UInt8}, Nothing} = nothing
elapsed::Union{HTTPTimedelta, Nothing} = nothing
status_code::Union{Int64, Nothing} = nothing
end

    • text_content: HTTP-ответ в текстовом представлении;

    • bytes_content: HTTP-ответ в байтовом представлении;

    • elapsed: время, затраченное на осуществление обработки запроса;

    • status_code: статус операции HTTP-запроса.

function get(device::HttpType, endpoint::String, request_data::HTTPRequestData, headers::Dict{String, String}=Dict(), timeout::Union{Int64, Nothing}=nothing)::HTTPResponse

GET-запрос REST API.

Аргументы

  • device::HttpType: объект типа HTTP.Http().

  • endpoint::String: конечная точка для обращения к HTTP-ресурсу.

  • request_data::HTTPRequestData: объект типа HTTPRequestData. HTTPRequestData имеет сигнатуру:

    Base.@kwdef struct HTTPRequestData
  params::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
  data::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
  json_data::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
  files::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
end

Описание: Тело запроса (если включает в себя данные) и json-данные (если есть)

  • params: параметры

    • Тип: словарь или nothing (необязательный).

    • Назначение: параметры URL-строки запроса (то, что идет после ? в адресе). Пример: {"page": 1, "limit": 20, "sort": "name"} → ?page=1&limit;=20&sort;=name.

    • Поддерживаемые типы значений:

      • Числа (целые и дробные);

      • Строки;

      • Логические значения (true/false);

      • Бинарные данные (байты);

      • Списки примитивных типов;

    Вложенные словари.

  • data: данные

    • Тип: словарь или nothing (необязательный).

    • Назначение: данные для тела запроса в формате x-www-form-urlencoded.

    • Использование: для отправки форм обычных данных (не файлов). Пример: {"username": "john", "password": "secret"}

    • Поддерживаемые типы: такие же, как у params.

  • json_data: JSON-данные

    • Тип: словарь или nothing (необязательный).

    • Назначение: данные для тела запроса в формате JSON.

    • Использование: для REST API, где ожидается JSON. Пример: {"user": {"name": "John", "age": 30}}.

    • Особенность: автоматически сериализуется в JSON строку.

    • Поддерживаемые типы: такие же, как у params.

  • files: файлы

    • Тип: словарь или nothing (необязательный).

    • Назначение: данные для загрузки файлов (мультипарт-запросы).

    • Использование: для отправки файлов через формы. Пример: {"avatar": "binary_data", "document": "file_content"}.

    • Поддерживаемые типы: такие же, как у params, но обычно содержит бинарные данные.

    • Пример создания:

    julia-repl params = Dict("param1" => "value1", "param2" => "value2") request_data = HTTPRequestData(params=params, data=nothing, json_data=nothing, files=nothing)

  • headers: дополнительные заголовки. Например, настройка заголовков соединения и MIME-type запросов:

julia-repl headers = Dict{String, String}() headers["connection"] = "keep-alive" headers["Accept"] = "application/json"

  • timeout: таймаут на ожидание ответа в секундах. Возвращает HTTPResponse (объект типа HTTPResponse). Пример:

julia-repl Base.@kwdef struct HTTPResponse text_content::Union{String, Nothing} = nothing bytes_content::Union{Vector{UInt8}, Nothing} = nothing elapsed::Union{HTTPTimedelta, Nothing} = nothing status_code::Union{Int64, Nothing} = nothing end - text_content: HTTP-ответ в текстовом представлении; - bytes_content: HTTP-ответ в байтовом представлении; - elapsed: время, затраченное на осуществление обработки запроса; - status_code: статус операции HTTP-запроса.

function init_session(device::HttpType, base_url::String="", auth::Union{Tuple{String}, String, Nothing}=nothing, auth_type::String="bearer", headers::Dict{String, String}=Dict(), timeout::Int64=30, verify_ssl::Bool=true)::Bool

Инициализация HTTP клиента для общения с HTTP-сервером.

Arguments

  • device: an object of the HTTP.Http() type.

  • base_url: the base URL for all requests.

  • auth: authorization data, either a tuple (username, password), or a string with a token.

  • auth_type: authentication type (basic, digest, or bearer).

  • headers: default headers to include in each request.

  • timeout: default response timeout in seconds.

  • verify_ssl: verification of SSL certificates (true — enabled, false — disabled).

function patch(device::HttpType, endpoint::String, request_data::HTTPRequestData, headers::Dict{String, String}=Dict(), timeout::Union{Int64, Nothing}=nothing)::HTTPResponse

PATCH-запрос REST API.

Аргументы

  • device::HttpType: объект типа HTTP.Http().

  • endpoint::String: конечная точка для обращения к HTTP-ресурсу.

  • request_data::HTTPRequestData: объект типа HTTPRequestData. HTTPRequestData имеет сигнатуру:

    Base.@kwdef struct HTTPRequestData
  params::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
  data::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
  json_data::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
  files::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
end

Описание: Тело запроса (если включает в себя данные) и json-данные (если есть)

  • params: параметры

    • Тип: словарь или nothing (необязательный).

    • Назначение: параметры URL-строки запроса (то, что идет после ? в адресе). Пример: {"page": 1, "limit": 20, "sort": "name"} → ?page=1&limit;=20&sort;=name.

    • Поддерживаемые типы значений:

      • Числа (целые и дробные);

      • Строки;

      • Логические значения (true/false);

      • Бинарные данные (байты);

      • Списки примитивных типов;

    Вложенные словари.

  • data: данные

    • Тип: словарь или nothing (необязательный).

    • Назначение: данные для тела запроса в формате x-www-form-urlencoded.

    • Использование: для отправки форм обычных данных (не файлов). Пример: {"username": "john", "password": "secret"}

    • Поддерживаемые типы: такие же, как у params.

  • json_data: JSON-данные

    • Тип: словарь или nothing (необязательный).

    • Назначение: данные для тела запроса в формате JSON.

    • Использование: для REST API, где ожидается JSON. Пример: {"user": {"name": "John", "age": 30}}.

    • Особенность: автоматически сериализуется в JSON строку.

    • Поддерживаемые типы: такие же, как у params.

  • files: файлы

    • Тип: словарь или nothing (необязательный).

    • Назначение: данные для загрузки файлов (мультипарт-запросы).

    • Использование: для отправки файлов через формы. Пример: {"avatar": "binary_data", "document": "file_content"}.

    • Поддерживаемые типы: такие же, как у params, но обычно содержит бинарные данные.

    • Пример создания:

    julia-repl params = Dict("param1" => "value1", "param2" => "value2") request_data = HTTPRequestData(params=params, data=nothing, json_data=nothing, files=nothing)

  • headers: дополнительные заголовки. Например, настройка заголовков соединения и MIME-type запросов:

julia-repl headers = Dict{String, String}() headers["connection"] = "keep-alive" headers["Accept"] = "application/json"

  • timeout: таймаут на ожидание ответа в секундах. Возвращает HTTPResponse (объект типа HTTPResponse). Пример:

julia-repl Base.@kwdef struct HTTPResponse text_content::Union{String, Nothing} = nothing bytes_content::Union{Vector{UInt8}, Nothing} = nothing elapsed::Union{HTTPTimedelta, Nothing} = nothing status_code::Union{Int64, Nothing} = nothing end - text_content: HTTP-ответ в текстовом представлении; - bytes_content: HTTP-ответ в байтовом представлении; - elapsed: время, затраченное на осуществление обработки запроса; - status_code: статус операции HTTP-запроса.

function post(device::HttpType, endpoint::String, request_data::HTTPRequestData, headers::Dict{String, String}=Dict(), timeout::Union{Int64, Nothing}=nothing)::HTTPResponse

POST-запрос REST API.

Arguments

  • device::HttpType: an object of the HTTP.Http() type.

  • endpoint::String: the endpoint for accessing an HTTP resource.

  • request_data::HTTPRequestData: an HTTPRequestData object. HTTPRequestData has a signature:

    Base.@kwdef struct HTTPRequestData
  params::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
  data::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
  json_data::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
  files::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
end

Description: Request body (if it includes data) and json data (if any)

  • params: parameters

    • Type: dictionary or nothing (optional).

    • Purpose: parameters of the URL query string (what comes after ? in the address). Example: {"page": 1, "limit": 20, "sort": "name"} → ?page=1&limit;=20&sort;=name.

    • Supported value types:

  • Numbers (integers and fractions);

    • Lines;

    • Logical values (true/false);

  • Binary data (bytes);

    • Lists of primitive types;

    Nested dictionaries.

  • data: data

    • Type: dictionary or nothing (optional).

    • Purpose: data for the request body in the x-www-form-urlencoded format.

    • Usage: to send forms of regular data (not files). Example: {"username": "john", "password": "secret"}

    • Supported types: the same as params.

  • json_data: JSON data

    • Type: dictionary or nothing (optional).

    • Purpose: data for the request body in JSON format.

    • Usage: for REST API, where JSON is expected. Example: {"user": {"name": "John", "age": 30}}.

    • Feature: automatically serialized to a JSON string.

    • Supported types: the same as params.

  • files: files

    • Type: dictionary or nothing (optional).

    • Purpose: data for uploading files (multipart requests).

    • Usage: to send files via forms. Example: {"avatar": "binary_data", "document": "file_content"}.

    • Supported types: the same as params, but usually contains binary data.

    • Example of creation:

`

  • headers: additional headings. For example, setting up connection headers and MIME-type requests:

= "keep-alive" headers["Accept"] = "application/json"]`

  • timeout: timeout for waiting for a response in seconds. Returns HTTPResponse (an HttpResponse type object). Example:

julia-repl Base.@kwdef struct HTTPResponse text_content::Union{String, Nothing} = nothing bytes_content::Union{Vector{UInt8}, Nothing} = nothing elapsed::Union{HTTPTimedelta, Nothing} = nothing status_code::Union{Int64, Nothing} = nothing end - text_content: HTTP response in text representation; - bytes_content: HTTP response in byte representation; - elapsed: time spent on request processing; - status_code: the status of the HTTP request operation.

function put(device::HttpType, endpoint::String, request_data::HTTPRequestData, headers::Dict{String, String}=Dict(), timeout::Union{Int64, Nothing}=nothing)::HTTPResponse

PUT-запрос REST API.

Аргументы

  • device::HttpType: объект типа HTTP.Http().

  • endpoint::String: конечная точка для обращения к HTTP-ресурсу.

  • request_data::HTTPRequestData: объект типа HTTPRequestData. HTTPRequestData имеет сигнатуру:

    Base.@kwdef struct HTTPRequestData
  params::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
  data::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
  json_data::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
  files::Union{Dict{String, Union{Int64, Float64, String, Bool, Vector{UInt8},
    Vector{Union{Int64, Float64, String, Bool}},
    Dict{String, Union{Int64, Float64, String, Bool,
      Dict{String, Union{Int64, Float64, String, Bool}}}}}}, Nothing} = nothing
end

Описание: Тело запроса (если включает в себя данные) и json-данные (если есть)

  • params: параметры

    • Тип: словарь или nothing (необязательный).

    • Назначение: параметры URL-строки запроса (то, что идет после ? в адресе). Пример: {"page": 1, "limit": 20, "sort": "name"} → ?page=1&limit;=20&sort;=name.

    • Поддерживаемые типы значений:

      • Числа (целые и дробные);

      • Строки;

      • Логические значения (true/false);

      • Бинарные данные (байты);

      • Списки примитивных типов;

    Вложенные словари.

  • data: данные

    • Тип: словарь или nothing (необязательный).

    • Назначение: данные для тела запроса в формате x-www-form-urlencoded.

    • Использование: для отправки форм обычных данных (не файлов). Пример: {"username": "john", "password": "secret"}

    • Поддерживаемые типы: такие же, как у params.

  • json_data: JSON-данные

    • Тип: словарь или nothing (необязательный).

    • Назначение: данные для тела запроса в формате JSON.

    • Использование: для REST API, где ожидается JSON. Пример: {"user": {"name": "John", "age": 30}}.

    • Особенность: автоматически сериализуется в JSON строку.

    • Поддерживаемые типы: такие же, как у params.

  • files: файлы

    • Тип: словарь или nothing (необязательный).

    • Назначение: данные для загрузки файлов (мультипарт-запросы).

    • Использование: для отправки файлов через формы. Пример: {"avatar": "binary_data", "document": "file_content"}.

    • Поддерживаемые типы: такие же, как у params, но обычно содержит бинарные данные.

    • Пример создания:

    julia-repl params = Dict("param1" => "value1", "param2" => "value2") request_data = HTTPRequestData(params=params, data=nothing, json_data=nothing, files=nothing)

  • headers: дополнительные заголовки. Например, настройка заголовков соединения и MIME-type запросов:

julia-repl headers = Dict{String, String}() headers["connection"] = "keep-alive" headers["Accept"] = "application/json"

  • timeout: таймаут на ожидание ответа в секундах. Возвращает HTTPResponse (объект типа HTTPResponse). Пример:

julia-repl Base.@kwdef struct HTTPResponse text_content::Union{String, Nothing} = nothing bytes_content::Union{Vector{UInt8}, Nothing} = nothing elapsed::Union{HTTPTimedelta, Nothing} = nothing status_code::Union{Int64, Nothing} = nothing end - text_content: HTTP-ответ в текстовом представлении; - bytes_content: HTTP-ответ в байтовом представлении; - elapsed: время, затраченное на осуществление обработки запроса; - status_code: статус операции HTTP-запроса.

function remove_header(device::HttpType, key::String)::Nothing

Функция для удаления указанного заголовков запроса из существующих заголовков.

Arguments

  • device::HttpType: an object of the HTTP.Http() type.

  • key::String: the key of the request header to be set.

function set_header(device::HttpType, key::String, value::String)::Nothing

A function for setting request headers to already existing headers.

Arguments

  • device::HttpType: an object of the HTTP.Http() type.

  • key::String: the key of the request header to be set.