Skip to content

Blue API

In today's post, I will talk a little bit about Blue API, our public-facing, as well as internal APIs. Blue API allows you to programmatically access our services such as Ripple and WavePro. It uses protocol buffers for its service and message definitions, and gRPC for implementation and server/client stub generation. It also uses grpc-gateway for proxying JSON/REST requests to gRPC, and generating OpenAPI documentation. This way, you have the option to use our APIs using either gRPC or JSON/REST, or both.


Blue API starts with our API definitions. You can find the repository here. Once compiled, it will generate our main SDK along with the other SDKs we support. (By the way, if you're a user and have a particular programming language you want supported, contact us at and we will try to prioritize it.) The build also generates our OpenAPI reference documentation here. Our team then uses the generated SDK, blue-sdk-go (we use Go as our main programming language), to implement the necessary gRPC services in the backend. As a client, you can either call our gRPC services directly using the supported SDKs, or call our HTTP proxies through an HTTP client such as curl, or any HTTP library which is part of most modern programming languages.


Blue API uses client credentials (tokens) for authentication. You can check this detailed guide for more information.


Here's an example Go code on how to use the SDK to call our gRPC services directly:

ctx := context.Background()
client, _ := iam.NewClient(ctx)
defer client.Close()
out, err := client.WhoAmI(ctx, &iam.WhoAmIRequest{})
log.Println(out, err)

Here's another example using curl (uses our bluectl tool to generate the token):

$ curl -H "Authorization: Bearer $(bluectl token)" \ | jq


At the moment, Blue API is still a work in progress. Most of the APIs currently supported in Ripple and WavePro are still not available. In the meantime, you can still use our JSON/REST APIs here. We plan to upgrade as many of our JSON/REST APIs as possible over to gRPC as it is significantly more efficient in terms of throughput and CPU usage compared to JSON/REST API. However, we don't intend to deprecate our JSON/REST APIs once the transition is completed. You should be able to use both.