{"id":20626368,"url":"https://github.com/jaeyson/open_api_typesense","last_synced_at":"2026-04-26T05:00:44.423Z","repository":{"id":261761272,"uuid":"885270759","full_name":"jaeyson/open_api_typesense","owner":"jaeyson","description":"Restful client for Typesense with adherence to Open API spec 3 (formerly Swagger)","archived":false,"fork":false,"pushed_at":"2026-04-26T03:00:17.000Z","size":612,"stargazers_count":2,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-26T04:25:35.235Z","etag":null,"topics":["elixir","open-api","open-api-v3","restful-api","swagger"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/open_api_typesense","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jaeyson.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-08T09:24:37.000Z","updated_at":"2026-04-26T02:59:40.000Z","dependencies_parsed_at":"2024-12-19T01:25:43.508Z","dependency_job_id":"5fda0285-f600-4b1f-b274-5b66d01f77fe","html_url":"https://github.com/jaeyson/open_api_typesense","commit_stats":null,"previous_names":["jaeyson/open_api_typesense"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/jaeyson/open_api_typesense","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaeyson%2Fopen_api_typesense","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaeyson%2Fopen_api_typesense/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaeyson%2Fopen_api_typesense/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaeyson%2Fopen_api_typesense/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jaeyson","download_url":"https://codeload.github.com/jaeyson/open_api_typesense/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaeyson%2Fopen_api_typesense/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32286271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"online","status_checked_at":"2026-04-26T02:00:05.962Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elixir","open-api","open-api-v3","restful-api","swagger"],"created_at":"2024-11-16T13:12:48.897Z","updated_at":"2026-04-26T05:00:44.416Z","avatar_url":"https://github.com/jaeyson.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenApiTypesense\n\nRestful client for Typesense with adherence to Open API spec 3 (formerly Swagger)\n\n[![Hex.pm](https://img.shields.io/hexpm/v/open_api_typesense)](https://hex.pm/packages/open_api_typesense)\n[![Hexdocs.pm](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/open_api_typesense)\n[![Coverage Status](https://coveralls.io/repos/github/jaeyson/open_api_typesense/badge.svg?branch=main)](https://coveralls.io/github/jaeyson/open_api_typesense?branch=main)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/965dd3f8866d49c3b3e82edd0f6270cb)](https://app.codacy.com/gh/jaeyson/open_api_typesense/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n[![codescenene Average Code Health](https://codescene.io/projects/63240/status-badges/average-code-health)](https://codescene.io/projects/63240)\n\n[![CI v30.1](https://github.com/jaeyson/open_api_typesense/actions/workflows/ci_v30.1.yml/badge.svg)](https://github.com/jaeyson/open_api_typesense/actions/workflows/ci_v30.1.yml)\n[![CI v30.0](https://github.com/jaeyson/open_api_typesense/actions/workflows/ci_v30.0.yml/badge.svg)](https://github.com/jaeyson/open_api_typesense/actions/workflows/ci_v30.0.yml)\n[![CI v29.0](https://github.com/jaeyson/open_api_typesense/actions/workflows/ci_v29.0.yml/badge.svg)](https://github.com/jaeyson/open_api_typesense/actions/workflows/ci_v29.0.yml)\n[![CI v28.0](https://github.com/jaeyson/open_api_typesense/actions/workflows/ci_v28.0.yml/badge.svg)](https://github.com/jaeyson/open_api_typesense/actions/workflows/ci_v28.0.yml)\n[![CI v27.1](https://github.com/jaeyson/open_api_typesense/actions/workflows/ci_v27.1.yml/badge.svg)](https://github.com/jaeyson/open_api_typesense/actions/workflows/ci_v27.1.yml)\n[![CI v27.0](https://github.com/jaeyson/open_api_typesense/actions/workflows/ci_v27.0.yml/badge.svg)](https://github.com/jaeyson/open_api_typesense/actions/workflows/ci_v27.0.yml)\n[![CI v26.0](https://github.com/jaeyson/open_api_typesense/actions/workflows/ci_v26.0.yml/badge.svg)](https://github.com/jaeyson/open_api_typesense/actions/workflows/ci_v26.0.yml)\n\n[![Dependabot](https://img.shields.io/badge/Dependabot-enabled-green)](https://github.com/jaeyson/open_api_typesense/pulls/app%2Fdependabot)\n[![Hex.pm](https://img.shields.io/hexpm/l/open_api_typesense)](https://hexdocs.pm/open_api_typesense/license.html)\n[![Latest Typesense compatible](https://img.shields.io/badge/Latest%20Typesense%20compatible-v30.1-%230F35BC)](https://typesense.org/docs/30.1/api)\n\n**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.\n\n\u003e #### Upgrading to v1 {: .warning}\n\u003e\n\u003e The breaking change here is `conn` is now part of `opts`\n\u003e when calling functions, see example below:\n\n```elixir\n# pre-v1\nCollections.get_collections(conn, opts)\n\n# v1\nCollections.get_collections(conn: conn)\n\n# another way (v1)\nopts = [limit: 1, conn: conn]\nCollections.get_collections(opts)\n\n# or (v1)\nCollections.get_collections(limit: 1, conn: conn)\n```\n## Installation\n\nIf [available in Hex](https://hex.pm/docs/publish), the package can be installed\nby adding `open_api_typesense` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:open_api_typesense, \"~\u003e 1.3\"}\n\n    # Or from GitHub repository, if you want the latest greatest from main branch\n    {:open_api_typesense, git: \"https://github.com/jaeyson/open_api_typesense.git\"}\n  ]\nend\n```\n\nDocumentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)\nand published on [HexDocs](https://hexdocs.pm). Once published, the docs can\nbe found at \u003chttps://hexdocs.pm/open_api_typesense\u003e.\n\n## Getting started\n\n### Adding credentials\n\nSpin up local Typesense instance\n\n```bash\ndocker compose up -d\n\n# check if \"peer refreshed\" in logs\ndocker container logs --follow --tail 50 typesense\n```\n\n```elixir\n# e.g. config/runtime.exs\nif config_env() == :prod do # if you'll use this in prod environment\n  config :open_api_typesense,\n    api_key: \"xyz\",\n    host: \"localhost\",\n    port: 8108,\n    scheme: \"http\"\n  ...\n```\n\n\u003e #### `options` key {: .tip}\n\u003e\n\u003e The `options` key can be used to pass additional configuration\n\u003e options such as custom Finch instance or receive timeout\n\u003e settings. You can add any options supported by Req here. For\n\u003e more details check [Req documentation](https://hexdocs.pm/req/Req.Steps.html#run_finch/1-request-options).\n\n```\nconfig :open_api_typesense,\n  api_key: \"credential\", # Admin API key\n  host: \"111222333aaabbbcc-9.x9.typesense.net\", # Nodes\n  port: 443,\n  scheme: \"https\"\n  options: [finch: MyApp.CustomFinch] # \u003c- add options\n```\n\n\u003e #### during tests {: .tip}\n\u003e\n\u003e If you have a different config for your app, consider \n\u003e adding it in `config/test.exs`.\n\n\nFor Cloud hosted, you can generate and obtain the credentials from cluster instance admin interface:\n\n```elixir\nconfig :open_api_typesense,\n  api_key: \"credential\", # Admin API key\n  host: \"111222333aaabbbcc-9.x9.typesense.net\", # Nodes\n  port: 443,\n  scheme: \"https\"\n```\n\n## Using another connection via maps\n\nYou might be using a connection that changes dynamically. You can pass it as a map:\n\n```elixir\ncustom_conn = %{api_key: \"xyz\", host: \"localhost\", port: 8108, scheme: \"http\"}\nOpenApiTypesense.Health(conn: conn)\n```\n\n## Using another HTTP client\n\nIn order to use another HTTP client, OpenApiTypesense has a\ncallback function ([Behaviours](https://hexdocs.pm/elixir/typespecs.html#behaviours))\ncalled `request` that contains 2 args:\n\n1. `conn`: your connection map\n2. `params`: payload, header, and client-related stuffs.\n\n\u003e #### `conn` and `params` {: .info}\n\u003e\n\u003e you can change the name `conn` and/or `params` however you want,\n\u003e since it's just a variable.\n\nHere's a custom client example ([`HTTPoison`](https://hexdocs.pm/httpoison/readme.html))\nin order to match the usage:\n\n\u003c!-- tabs-open --\u003e\n\n### Client module\n\n```elixir\ndefmodule MyApp.CustomClient do\n  @behaviour OpenApiTypesense.Client\n  \n  @impl OpenApiTypesense.Client\n  def request(conn, params) do\n    url = %URI{\n      scheme: conn.scheme,\n      host: conn.host,\n      port: conn.port,\n      path: params.url,\n      query: URI.encode_query(params[:query] || %{})\n    }\n    |\u003e URI.to_string()\n\n    request = %HTTPoison.Request{method: params.method, url: url}\n\n    request =\n      if params[:request] do\n        [{content_type, _schema}] = params.request\n\n        headers = [\n          {\"X-TYPESENSE-API-KEY\", conn.api_key}\n          {\"Content-Type\", content_type}\n        ]\n\n        %{request | headers: headers}\n      else\n        request\n      end\n\n    request =\n      if params[:body] do\n        %{request | body: Jason.encode!(params.body)}\n      else\n        request\n      end\n\n    HTTPoison.request!(request)\n  end\nend\n```\n\n### Client config\n\n```elixir\nconfig :open_api_typesense,\n  api_key: \"xyz\", # Admin API key\n  host: \"localhost\", # Nodes\n  port: 8108,\n  scheme: \"http\",\n  client: MyApp.CustomClient # \u003c- add this\n```\n\n\u003c!-- tabs-close --\u003e\n\nCheck [the examples](./guides/custom_http_client.md) on some HTTP client implementations.\n\n## Adding [cache, retry, compress_body](https://hexdocs.pm/req/Req.html#new/1) in the built in client\n\nE.g. when a user wants to change `retry` and `cache` options\n\n```elixir\nExTypesense.get_collection(\"companies\", req: [retry: false, cache: true])\n```\n\nSee implementation [OpenApiTypesense.Client](`OpenApiTypesense.Client`) https://github.com/jaeyson/open_api_typesense/blob/main/lib/open_api_typesense/client.ex\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaeyson%2Fopen_api_typesense","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaeyson%2Fopen_api_typesense","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaeyson%2Fopen_api_typesense/lists"}