OpenApiTypesense

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

Note: the only place where ai is used/integrated is in PR reviews. I am NOT interested in adding/integrating ai generated code in this codebase, as this little library can be fit in my mental model. ai has it’s own great use case, it’s just that I wanted to be hands-on with these projects.

Upgrading to v1

The breaking change here is conn is now part of opts when calling functions, see example below:

# 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)

# or (v1)
Collections.get_collections(limit: 1, conn: conn)

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.3"}

    # 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"
  ...

options key

The options key can be used to pass additional configuration options such as custom Finch instance or receive timeout settings. You can add any options supported by Req here. For more details check Req documentation.

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

during tests

If you have a different config for your app, consider adding it in config/test.exs.

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.

conn and params

you can change the name conn and/or params however you want, since it's just a variable.

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.Clienthttps://github.com/jaeyson/open_api_typesense/blob/main/lib/open_api_typesense/client.ex