{"id":21185604,"url":"https://github.com/raystack/proton","last_synced_at":"2026-01-02T15:08:40.204Z","repository":{"id":36970011,"uuid":"350649542","full_name":"raystack/proton","owner":"raystack","description":"This repository is home to the original protobuf interface definitions which are used throughout the Raystack ecosystem.","archived":false,"fork":false,"pushed_at":"2024-04-10T06:55:21.000Z","size":1540,"stargazers_count":52,"open_issues_count":9,"forks_count":22,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-04-10T07:23:21.675Z","etag":null,"topics":["protobuf","schema"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raystack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2021-03-23T09:19:41.000Z","updated_at":"2024-04-10T07:23:23.283Z","dependencies_parsed_at":"2023-10-28T09:27:01.627Z","dependency_job_id":"cddc0afc-aabc-4e1f-90cd-74012e14f988","html_url":"https://github.com/raystack/proton","commit_stats":null,"previous_names":["raystack/proton","odpf/proton"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raystack%2Fproton","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raystack%2Fproton/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raystack%2Fproton/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raystack%2Fproton/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raystack","download_url":"https://codeload.github.com/raystack/proton/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243639558,"owners_count":20323510,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["protobuf","schema"],"created_at":"2024-11-20T18:17:16.786Z","updated_at":"2026-01-02T15:08:40.200Z","avatar_url":"https://github.com/raystack.png","language":null,"readme":"# Proton\n\nThis repository contains the original interface definitions of Raystack APIs that support both REST and gRPC protocols. Reading the original interface definitions can provide a better understanding of Raystack APIs and help you to utilize them more efficiently. You can also use these definitions with open source tools to generate client libraries, documentation, and other artifacts.\n\n## Overview\n\nRaystack APIs are typically deployed as API services that are hosted under different DNS names. One API service may implement multiple APIs and multiple versions of the same API.\n\nRaystack APIs use [Protocol Buffers](https://github.com/google/protobuf) version 3 (proto3) as their Interface Definition Language (IDL) to define the API interface and the structure of the payload messages. The same interface definition is used for both REST and RPC versions of the API, which can be accessed over different wire protocols.\n\nThere are several ways of accessing Raystack APIs:\n\n1.  JSON over HTTP: You can access all Raystack APIs directly using JSON over HTTP, using any API client libraries.\n2.  Protocol Buffers over gRPC: You can access Raystack APIs published in this repository through [GRPC](https://github.com/grpc), which is a high-performance binary RPC protocol over HTTP/2. It offers many useful features, including request/response multiplex and full-duplex streaming.\n\n## Structure\n\nThis repository uses a directory hierarchy that reflects the Raystack API product structure. In general, every API has its own root directory, and each major version of the API has its own subdirectory.\n\nThe proto package names exactly match the directory: this makes it easy to locate the proto definitions and ensures that the generated client libraries have idiomatic namespaces in most programming languages.\n\n## Usage\n\nProton does not provide compiled language specific proto files or the descriptor sets for the respective protos. It is upto the users to pull these protos and use `protoc` or `buf` for language specific compiled files and have dependencies/imports in their code.\n\nTo generate gRPC source code for Protobuf APIs in this repository, you first need to install buf on your local machine. For next step, add `buf.gen.yaml` at the root of your project.\n\n```yaml\nversion: v1\nplugins:\n  - name: go\n    out: api\n    opt: paths=source_relative\n```\n\nRun below command to generate your proto to `/api` folder.\n\n```\nbuf generate\n```\n\nUse below command if you just want to target specific package/folder\n\n```\nbuf generate --path raystack/assets\n```\n\nCheck out Compass [implementation](https://github.com/raystack/compass) for reference.\n\n## Python Client\n\nA pre-built Python client package is available:\n\n### Installation\n\n```bash\npip install raystack-proton\n```\n\n**PyPI:** https://pypi.org/project/raystack-proton/\n\n### Usage\n\nSee the [Python README](python/README.md) for detailed usage examples.\n\n## JavaScript/TypeScript Client\n\nA pre-built JavaScript/TypeScript client package is available for browser and Node.js environments:\n\n### Installation\n\n```bash\nnpm install @raystack/proton\n```\n\n**NPM:** https://npmjs.com/package/@raystack/proton\n\n### Usage\n\nSee the [JavaScript README](js/README.md) for detailed usage examples.\n\nFor browser applications using TanStack Query:\n```bash\nnpm install @raystack/proton @tanstack/react-query\n```\n\n### Usage\n\n#### Browser Example (React)\n\n```typescript\nimport { FrontierService } from '@raystack/proton/frontier';\nimport { createConnectTransport } from '@connectrpc/connect-web';\nimport { createPromiseClient } from '@connectrpc/connect';\n\n// Create transport\nconst transport = createConnectTransport({\n  baseUrl: 'https://api.example.com'\n});\n\n// Create client\nconst client = createPromiseClient(FrontierService, transport);\n\n// Use the client\nasync function listUsers() {\n  const response = await client.listUsers({\n    pageSize: 10\n  });\n  return response.users;\n}\n```\n\n#### With TanStack Query\n\n```typescript\nimport { FrontierServiceQueries } from '@raystack/proton/frontier';\nimport { useQuery } from '@tanstack/react-query';\n\nfunction UsersList() {\n  const { data, isLoading } = useQuery(\n    FrontierServiceQueries.listUsers(transport, { pageSize: 10 })\n  );\n\n  if (isLoading) return \u003cdiv\u003eLoading...\u003c/div\u003e;\n  \n  return (\n    \u003cul\u003e\n      {data?.users?.map(user =\u003e (\n        \u003cli key={user.id}\u003e{user.name}\u003c/li\u003e\n      ))}\n    \u003c/ul\u003e\n  );\n}\n```\n\n#### Node.js Example\n\n```typescript\nimport { FrontierService } from '@raystack/proton/frontier';\nimport { createConnectTransport } from '@connectrpc/connect-node';\nimport { createPromiseClient } from '@connectrpc/connect';\n\nconst transport = createConnectTransport({\n  baseUrl: 'https://api.example.com',\n  httpVersion: '2'\n});\n\nconst client = createPromiseClient(FrontierService, transport);\n\nconst users = await client.listUsers({ pageSize: 10 });\nconsole.log(users);\n```\n\n### Available Services\n\nThe package provides exports for all Raystack services:\n- `@raystack/proton/frontier` - Frontier API\n- `@raystack/proton/compass` - Compass API\n- `@raystack/proton/assets` - Assets API\n- `@raystack/proton/guardian` - Guardian API\n- And more...\n\nEach service export includes:\n- Service client (e.g., `FrontierService`)\n- TanStack Query helpers (e.g., `FrontierServiceQueries`) - optional\n- TypeScript types and interfaces\n\n## Contribute\n\n\u003cdetails\u003e\n  \u003csummary\u003ePrerequisites:\u003c/summary\u003e\n  \n- [Buf](https://docs.buf.build/installation)\n- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)\n\n\u003c/details\u003e\n\nYou can run following command for linting protobuf files\n\n```sh\nbuf lint\n```\n\nRun following command to format protobuf files\n\n```sh\nbuf format -w\n```\n\nYou can run following command for formatting protobuf files\n\n```sh\n$ buf format -w\n```\n\nYou can add proto files when you need to introduce proto for Raystack projects. If you need to modify proto files, you need to ensure backward compatibility. To ensure the backward compatibility of your changes, you can run\n\n```sh\nbuf breaking --against '.git#branch=master'\n```\n\n## License\n\nProton is [Apache 2.0](LICENSE) licensed.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraystack%2Fproton","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraystack%2Fproton","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraystack%2Fproton/lists"}