GitHub - vegaprotocol/api: Auto-generated API clients (original) (raw)

Vega API

Version: 0.41.0

This repository contains everything you need for interacting with the Vega APIs.

There are currently 3 APIs:

• gRPC
• GraphQL
• REST

gRPC

See https://grpc.io/ for general information on gRPC.

Vega provides a rich gRPC API. For a complete list of endpoints, see proto/api/trading.proto:

• Use TradingService for:
  • Prepare* endpoints are there for convenience, and will be removed in the near future
  • SubmitTransaction receives and executes a signed transaction. For transaction signing, see go-wallet.
• Use TradingDataService for public information on:
  • assets, e.g. Ethereum ERC20 tokens
  • balances for accounts: general, margin
  • market data and metadata
  • information on orders and trades
  • Governance data: proposals, votes
  • event stream subscriptions for the above

Before writing your own API client (either manually or using auto-generation), check if a pre-created on is already available. See Auto-generated gRPC clients below.

GraphQL

See https://graphql.org/ for general information on GraphQL.

Vega provides a fully-featured GraphQL API. For the complete schema, see graphql/schema.graphql.

The GraphQL Playground is enabled for convenience on Testnet non-validator nodes: https://lb.testnet.vega.xyz/playground.

It is possible to use nested queries that return only the desired information.

REST

Vega provides a limited REST API. Streaming of events is not supported.

For an OpenAPI json file that describes all available endpoints, see rest/api/trading.swagger.json. The mapping between gRPC endpoints and their REST equivalent is found in rest/grpc-rest-bindings.yml.

Auto-generated gRPC clients

Vega uses buf to auto-generate API clients in various programming languages. The list of currently supported clients is found in buf.gen.yaml, and the full build process is in the Makefile.

The per-language API clients are found in grpc/clients/.

Pull requests for additional languages are gratefully received.

Examples

Some example/demonstration programs are maintained in this repository. They are intended to be stand-alone programs that can be run by people copying and editing the source code.

Information for maintainers

Update process - gRPC

Install buf: https://docs.buf.build/installation/

Copy proto files from Core

cd .../api # repo root dir VEGACORE=/path/to/go/src/vega make preproto

Generate gRPC API clients, gRPC documentation, REST OpenAPI json.

make proto

Run tests

GRPC_NODE=veganode.example.com:1234 WALLETSERVER=https://vegawallet.example.com make test

Java gRPC generation

Run the update for gRPC in general and this will generate all the Java source files.

Install maven

• Linux: sudo apt install maven

Run ./make-jar.sh in the grpc/clients/java directory.

Update process - GraphQL

Copy schema.graphql from Core

cd .../api/graphql VEGACORE=/path/to/go/src/vega make pregraphql

Generate GraphQL documentation

make graphql

Release process

./setversion.sh 1.2.3 # no "v" prefix

Licence

Distributed under the MIT License. See LICENSE for more information.