API Reference

Client(root::String;
    headers::Dict{String,String}=Dict{String,String}(),
    get_return_type::Function=get_api_return_type,
    long_polling_timeout::Int=DEFAULT_LONGPOLL_TIMEOUT_SECS,
    timeout::Int=DEFAULT_TIMEOUT_SECS,
    pre_request_hook::Function=noop_pre_request_hook,
    escape_path_params::Union{Nothing,Bool}=nothing,
    chunk_reader_type::Union{Nothing,Type{<:AbstractChunkReader}}=nothing,
    verbose::Union{Bool,Function}=false,
)

Create a new OpenAPI client context.

A client context holds common information to be used across APIs. It also holds a connection to the server and uses that across API calls. The client context needs to be passed as the first parameter of all API calls.

Parameters:

• root: The root URL of the server. This is the base URL that will be used for all API calls.

Keyword parameters:

• headers: A dictionary of HTTP headers to be sent with all API calls.
• get_return_type: A function that is called to determine the return type of an API call. This function is called with the following parameters:
  • return_types: A dictionary of regular expressions and their corresponding return types. The regular expressions are matched against the HTTP status code of the response.
  • response_code: The HTTP status code of the response.
  • response_data: The response data as a string.
  The function should return the return type to be used for the API call.
• long_polling_timeout: The timeout in seconds for long polling requests. This is the time after which the request will be aborted if no data is received from the server.
• timeout: The timeout in seconds for all other requests. This is the time after which the request will be aborted if no data is received from the server.
• pre_request_hook: A function that is called before every API call. This function must provide two methods:
  • pre_request_hook(ctx::Ctx): This method is called before every API call. It is passed the context object that will be used for the API call. The function should return the context object to be used for the API call.
  • pre_request_hook(resource_path::AbstractString, body::Any, headers::Dict{String,String}): This method is called before every API call. It is passed the resource path, request body and request headers that will be used for the API call. The function should return those after making any modifications to them.
• escape_path_params: Whether the path parameters should be escaped before being used in the URL. This is useful if the path parameters contain characters that are not allowed in URLs or contain path separators themselves.
• chunk_reader_type: The type of chunk reader to be used for streaming responses. This can be one of LineChunkReader, JSONChunkReader or RFC7464ChunkReader. If not specified, then the type is automatically determined based on the return type of the API call.
• verbose: Can be set either to a boolean or a function.
  • If set to true, then the client will log all HTTP requests and responses.
  • If set to a function, then that function will be called with the following parameters:
    • type: The type of message.
    • message: The message to be logged.

set_user_agent(client::Client, ua::String)

Set the User-Agent header to be sent with all API calls.

set_cookie(client::Client, ck::String)

Set the Cookie header to be sent with all API calls.

set_header(client::Client, name::String, value::String)

Set the specified header to be sent with all API calls.

set_timeout(client::Client, timeout::Int)

Set the timeout in seconds for all API calls.

hasproperty(x, s::Symbol)

Return a boolean indicating whether the object x has s as one of its own properties.

See also: propertynames, hasfield.

getproperty(value, name::Symbol)
getproperty(value, name::Symbol, order::Symbol)

The syntax a.b calls getproperty(a, :b). The syntax @atomic order a.b calls getproperty(a, :b, :order) and the syntax @atomic a.b calls getproperty(a, :b, :sequentially_consistent).

Examples

julia> struct MyType{T <: Number}
           x::T
       end

julia> function Base.getproperty(obj::MyType, sym::Symbol)
           if sym === :special
               return obj.x + 1
           else # fallback to getfield
               return getfield(obj, sym)
           end
       end

julia> obj = MyType(1);

julia> obj.special
2

julia> obj.x
1

One should overload getproperty only when necessary, as it can be confusing if the behavior of the syntax obj.f is unusual. Also note that using methods is often preferable. See also this style guide documentation for more information: Prefer exported methods over direct field access.

See also getfield, propertynames and setproperty!.

setproperty!(value, name::Symbol, x)
setproperty!(value, name::Symbol, x, order::Symbol)

The syntax a.b = c calls setproperty!(a, :b, c). The syntax @atomic order a.b = c calls setproperty!(a, :b, c, :order) and the syntax @atomic a.b = c calls setproperty!(a, :b, c, :sequentially_consistent).

See also setfield!, propertynames and getproperty.

getpropertyat(o::T, path...) where {T<:APIModel}

Returns the property at the specified path. The path can be a single property name or a chain of property names separated by dots, representing a nested property.

haspropertyat(o::T, path...) where {T<:APIModel}

Returns true if the supplied object has the property at the specified path.

ApiResponse

Represents the HTTP API response from the server. This is returned as the second return value from all API calls.

Properties available:

• status: the HTTP status code
• message: the HTTP status message
• headers: the HTTP headers
• raw: the raw response ( as a Downloads.Response object)

is_longpoll_timeout(ex::Exception)

Examine the supplied exception and return true if the reason is timeout of a long polling request. If the exception is a nested exception of type CompositeException or TaskFailedException, then navigates through the nested exception values to examine the leaves.

is_request_interrupted(ex::Exception)

Examine the supplied exception and return true if the reason is that the request was interrupted. If the exception is a nested exception of type CompositeException or TaskFailedException, then navigates through the nested exception values to examine the leaves.

storefile(api_call::Function;
    folder::AbstractString = pwd(),
    rename_file::String="",
    )::Tuple{Any,ApiResponse,String}

Helper method that stores the result of an API call that returns file
contents (as binary or text string) into a file.

Convenient to use it in a do block. Returns the path where file is stored additionally.

E.g.:
```
_result, _http_response, file = OpenAPI.Clients.storefile() do
    # Invoke the OpenaPI method that returns file contents.
    # This is the method that returns a tuple of (result, http_response).
    # The result is the file contents as binary or text string.
    fetch_file(api, "reports", "category1")
end
```

Parameters:

- `api_call`: The OpenAPI function call that returns file contents (as binary or text string). See example in method description.
- `folder`: Location to store file, defaults to `pwd()`.
- `filename`: Use this filename, overrides any filename that may be there in the `Content-Disposition` header.

Returns: (result, http_response, file_path)

openapi_generator(; port=8080, use_sudo=false)

Start an OpenAPI Generator Online container. Returns the URL of the OpenAPI Generator.

Optional arguments:

• port: The port to use for the OpenAPI Generator. Defaults to 8080.
• use_sudo: Whether to use sudo to run Docker commands. Defaults to false.

stop_openapi_generator(; use_sudo=false)

Stop and remove the OpenAPI Generator container, if it is running. Returns true if the container was stopped and removed, false otherwise.

generate(
    spec::Dict{String,Any};
    type::Symbol=:client,
    package_name::AbstractString="APIClient",
    export_models::Bool=false,
    export_operations::Bool=false,
    output_dir::AbstractString="",
    generator_host::AbstractString=GeneratorHost.Local
)

Generate client or server code from an OpenAPI spec using the OpenAPI Generator. The OpenAPI Generator must be running at the specified generator_host.

Returns the path to the generated code.

Optional arguments:

• type: The type of code to generate. Must be :client or :server. Defaults to :client.
• package_name: The name of the package to generate. Defaults to "APIClient".
• export_models: Whether to export models. Defaults to false.
• export_operations: Whether to export operations. Defaults to false.
• output_dir: The directory to save the generated code. Defaults to a temporary directory. Directory will be created if it does not exist.
• generator_host: The host of the OpenAPI Generator. Defaults to GeneratorHost.Local. Other possible values are GeneratorHost.OpenAPIGeneratorTech.Stable or GeneratorHost.OpenAPIGeneratorTech.Master, which point to the service hosted by OpenAPI org. It can also be any other URL where the OpenAPI Generator is running.

A locally hosted generator service is preferred by default for privacy reasons. Use openapi_generator to start a local container. Use stop_openapi_generator to stop the local generator service after use.

swagger_ui(spec; port=8080, use_sudo=false)
swagger_ui(spec_dir, spec_file; port=8080, use_sudo=false)

Start a Swagger UI container for the given OpenAPI spec file. Returns the URL of the Swagger UI.

Optional arguments:

• port: The port to use for the Swagger UI. Defaults to 8080.
• use_sudo: Whether to use sudo to run Docker commands. Defaults to false.

stop_swagger_ui(; use_sudo=false)

Stop and remove the Swagger UI container, if it is running. Returns true if the container was stopped and removed, false otherwise.

swagger_editor(; port=8080, use_sudo=false)
swagger_editor(spec; port=8080, use_sudo=false)
swagger_editor(spec_dir, spec_file; port=8080, use_sudo=false)

Start a Swagger Editor container with an optional OpenAPI spec file. Returns the URL of the Swagger Editor.

Optional arguments:

• port: The port to use for the Swagger Editor. Defaults to 8080.
• use_sudo: Whether to use sudo to run Docker commands. Defaults to false.

stop_swagger_editor(; use_sudo=false)

Stop and remove the Swagger Editor container, if it is running. Returns true if the container was stopped and removed, false otherwise.

lint(spec; use_sudo=false)
lint(spec_dir, spec_file; use_sudo=false)

Lint an OpenAPI spec file using Spectral.

Optional arguments:

• use_sudo: Whether to use sudo to run Docker commands. Defaults to false.