Connect-RPC vs gRPC vs REST: which to use when

Bareun serves the morphological analysis API from one server in three ways: Connect-RPC, gRPC, and REST (HTTP/1.1). Since the same LanguageService is exposed on the same port, you can freely choose the protocol to fit your client environment.

This page summarizes the differences between the three protocols and how to choose. The goal is to help you quickly decide "which is the most convenient in which environment."

The three protocols at a glance

The Bareun server is implemented with Go-based connect-go, so the same endpoint accepts all three protocols at once. For browsers, we recommend connect-web.

Item	Connect-RPC	gRPC	REST (HTTP/1.1)
Transport	HTTP/1.1, HTTP/2	HTTP/2	HTTP/1.1
Message	Protobuf / JSON	Protobuf	JSON
Direct browser calls	Possible (connect-web)	Difficult (proxy needed)	Possible
Streaming	Supported	Supported	Not supported
Typical client	JS (connect-web)	Python, Java, R	Any HTTP client
Recommended use	Web frontend	Bulk processing between servers	Simple integration and testing

How to choose

graph TD
  Q{Who is calling?} --> B[Browser/web app]
  Q --> S[Server/batch]
  Q --> T[Quick test]
  B --> CW[Connect-RPC<br/>connect-web]
  S --> G[gRPC<br/>bareunpy·Java·R]
  T --> R[REST<br/>curl·HTTP client]

For a web frontend, we recommend Connect-RPC (connect-web). You can call it directly from the browser without a separate proxy.
For server-to-server communication and bulk batches, gRPC is efficient. Protobuf binary encoding and HTTP/2 multiplexing give good throughput. The Python (bareunpy), Java, and R clients use this method.
For quick checks and simple integrations, REST is convenient. You can call it right away with curl or an HTTP library you already know.

Where to connect

Both the cloud and installed versions provide the same LanguageService. Only the address differs.

Environment	Address	Notes
Cloud	`api.bareun.ai:443`	TLS, API key required
Installed (native)	`localhost:5656`	Default port
Docker distribution	`localhost:5656`	Served directly by the server

One server, three entrances

The Bareun server accepts the same service definition (LanguageService) over three protocols at once. Even if you change the protocol, the request and response message structure (AnalyzeSyntaxRequest, Sentence, Token, Morpheme) is the same, so switching to another method later requires only small code changes.

Frequently asked questions

Q. Can't I call gRPC directly from a browser?

Browsers cannot directly call standard gRPC (which relies on HTTP/2 trailers). So from a browser, call the Bareun server (port 5656) directly with Connect-RPC (connect-web).

Q. Does the response differ by protocol?

No. The same LanguageService is exposed, so the analysis result (sentence, eojeol, and morpheme structure) is the same. You only need to specify the encoding type, which determines how positions (offsets) are computed, to match the client language's conventions.

Q. Which method has the best throughput?

For bulk processing, gRPC is generally advantageous, thanks to Protobuf binary encoding and HTTP/2 multiplexing. For single calls and simple integrations, however, the difference from REST is not very noticeable.

Q. What is the Bareun REST API path?

The Bareun server handles gRPC, connect-web, and HTTP+JSON all on one port with connect-go, so REST calls also use the Connect path POST /bareun.<Service>/<Method>. For example, morphological analysis is POST /bareun.LanguageService/AnalyzeSyntax. The old gateway path (/bareun/api/v1/...) and a separate Envoy frontend are not used.