stellarstation 0.0.5

Client stubs for accessing the StellarStation API

StellarStation API

The public API definition for StellarStation and supported client libraries / helpers.

This repository is currently under construction and is provided for reference. API implementation is in progress and documentation will continue to evolve. Feel free to send PRs to improve documentation when things are unclear or file issues with questions on usage.

Usage

The StellarStation API is based on gRPC. An API client can be written in any language supported by gRPC by following one of the language-specific guides here.

The main protocol definition used to generate language specific stub code is here.

Java

We provide precompiled client stubs for Java. Java users can just add a dependency on the stubs and don't need to compile the protocol into code themselves.

Gradle users should add the stellarstation-api artifact to their dependencies, e.g.,

dependencies {
    compile 'com.stellarstation.api:stellarstation-api:0.0.3'
}

Maven users would add to their pom.xml

<dependencies>
  <dependency>
    <groupId>com.stellarstation.api</groupId>
    <artifactId>stellarstation-api</artifactId>
    <version>0.0.3</version>
  </dependency>
</dependencies>

A full example of a Java API client can be found here.

Python

We provide precompiled client stubs for Python. Python users can install them with pip.

$  pip install --upgrade stellarstation

A full example of a Python API client can be found here.

Authentication

Authentication to the StellarStation API is done using JWT bearer tokens (https://jwt.io). When initializing an API client, make sure to register call credentials using the private key downloaded from the StellarStation Console. Details for registering call credentials on a gRPC stub can be found here. Note that if the key has been revoked on the console, it will not be usable to authenticate with the API.

Java

For Java, the grpc-auth and google-auth-library-oauth2-http libraries can be used to easily setup authentication of an API client.

// Load the private key downloaded from the StellarStation Console.
ServiceAccountJwtAccessCredentials credentials =
    ServiceAccountJwtAccessCredentials.fromStream(
        Resources.getResource("api-key.json").openStream(),
        URI.create("https://api.stellarstation.com"));

// Setup the gRPC client.
ManagedChannel channel =
    ManagedChannelBuilder.forAddress("localhost", 8081)
        .build();
StellarStationServiceStub client =
    StellarStationServiceGrpc.newStub(channel)
        .withCallCredentials(MoreCallCredentials.from(credentials));

Python

google-auth for Python can be used for authentication of an API client.

# Load the private key downloaded from the StellarStation Console.
credentials = google_auth_jwt.Credentials.from_service_account_file(
  'api-key.json',
  audience='https://api.stellarstation.com')

# Setup the gRPC client.
jwt_creds = google_auth_jwt.OnDemandCredentials.from_signing_credentials(
  credentials)
channel_credential = grpc.ssl_channel_credentials(open('tls.crt', 'br').read())
channel = google_auth_transport_grpc.secure_authorized_channel(
  jwt_creds, None, 'localhost:8080', channel_credential)
client = stellarstation_pb2_grpc.StellarStationServiceStub(channel)

Other languages

Other languages have similar methods for loading Service Account JWT Access Credentials. For example,

• C++ - https://github.com/grpc/grpc/blob/583f39ad94c0a14a50916e86a5ccd8c3c77ae2c6/include/grpcpp/security/credentials.h#L144
• Go - https://github.com/grpc/grpc-go/blob/96cefb43cfc8b2cd3fed9f19f59830bc69e30093/credentials/oauth/oauth.go#L60

Usage

When using proto files from this repository directly in client code, make sure to only use tagged releases. Using proto files from any non-tagged revision will likely not work correctly.