OpenApiTypesense

Restful client for Typesense with adherence to Open API spec 3 (formerly Swagger)

# pre-v1
Collections.get_collections(conn, opts)

# v1
Collections.get_collections(conn: conn)

# another way (v1)
opts = [limit: 1, conn: conn]
Collections.get_collections(opts)

Installation

If available in Hex, the package can be installed by adding open_api_typesense to your list of dependencies in mix.exs:

def deps do
  [
    {:open_api_typesense, "~> 1.0"}

    # Or from GitHub repository, if you want the latest greatest from main branch
    {:open_api_typesense, git: "https://github.com/jaeyson/open_api_typesense.git"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/open_api_typesense.

Getting started

Adding credentials

Spin up local Typesense instance

docker compose up -d

# check if "peer refreshed" in logs
docker container logs --follow --tail 50 typesense

# e.g. config/runtime.exs
if config_env() == :prod do # if you'll use this in prod environment
  config :open_api_typesense,
    api_key: "xyz",
    host: "localhost",
    port: 8108,
    scheme: "http"
  ...

config :open_api_typesense,
  api_key: "credential", # Admin API key
  host: "111222333aaabbbcc-9.x9.typesense.net", # Nodes
  port: 443,
  scheme: "https"
  options: [finch: MyApp.CustomFinch] # <- add options

For Cloud hosted, you can generate and obtain the credentials from cluster instance admin interface:

config :open_api_typesense,
  api_key: "credential", # Admin API key
  host: "111222333aaabbbcc-9.x9.typesense.net", # Nodes
  port: 443,
  scheme: "https"

Using another connection via maps

You might be using a connection that changes dynamically. You can pass it as a map:

custom_conn = %{api_key: "xyz", host: "localhost", port: 8108, scheme: "http"}
OpenApiTypesense.Health(conn: conn)

Using another HTTP client

In order to use another HTTP client, OpenApiTypesense has a callback function (Behaviours) called request that contains 2 args:

1. conn: your connection map
2. params: payload, header, and client-related stuffs.

Here's a custom client example (HTTPoison) in order to match the usage:

Client module

defmodule MyApp.CustomClient do
  @behaviour OpenApiTypesense.Client
  
  @impl OpenApiTypesense.Client
  def request(conn, params) do
    url = %URI{
      scheme: conn.scheme,
      host: conn.host,
      port: conn.port,
      path: params.url,
      query: URI.encode_query(params[:query] || %{})
    }
    |> URI.to_string()

    request = %HTTPoison.Request{method: params.method, url: url}

    request =
      if params[:request] do
        [{content_type, _schema}] = params.request

        headers = [
          {"X-TYPESENSE-API-KEY", conn.api_key}
          {"Content-Type", content_type}
        ]

        %{request | headers: headers}
      else
        request
      end

    request =
      if params[:body] do
        %{request | body: Jason.encode!(params.body)}
      else
        request
      end

    HTTPoison.request!(request)
  end
end

Client config

config :open_api_typesense,
  api_key: "xyz", # Admin API key
  host: "localhost", # Nodes
  port: 8108,
  scheme: "http",
  client: MyApp.CustomClient # <- add this

Check the examples on some HTTP client implementations.

Adding cache, retry, compress_body in the built in client

E.g. when a user wants to change retry and cache options

ExTypesense.get_collection("companies", req: [retry: false, cache: true])

See implementation OpenApiTypesense.Client https://github.com/jaeyson/open_api_typesense/blob/main/lib/open_api_typesense/client.ex