Client stubs for accessing the StellarStation API
Project description
StellarStation API
The public API definition for StellarStation and supported client libraries / helpers.
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.
Language-specific documentation:
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 or maintain backwards compatibility.
The API follows semantic versioning - any breaking, backwards incompatible change will be made while increasing the major version.
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.8.0'
}
Maven users would add to their pom.xml
<dependencies>
<dependency>
<groupId>com.stellarstation.api</groupId>
<artifactId>stellarstation-api</artifactId>
<version>0.8.0</version>
</dependency>
</dependencies>
A full example of a Java API client can be found here. You can also find tutorials to start your own Java client here.
We publish SNAPSHOT
builds to https://oss.jfrog.org/libs-snapshot/ for access to preview features.
The same caveats as using non-tagged releases applies - not all functions in SNAPSHOT
builds may
be implemented yet and there is no guarantee of backwards compatibility for SNAPSHOT
builds. It is
generally not recommended to use SNAPSHOT
builds without first consulting with your StellarStation rep.
Note for Alpine Linux users
For anyone trying to use the Java API client in an Alpine Linux container, they will find it doesn't work due to a limitation of gRPC with Java 8. There are many ways to work around this, such as using jetty-alpn or installing a version of Java 9+, but our recommendation for Java 8 users is to use distroless, which is similarly compact but will work fine with gRPC.
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.
Go
We provide precompiled client stubs for Go, found here.
import stellarstation "github.com/infostellarinc/go-stellarstation/api/v1"
NodeJS
We provide precompiled client stubs for NodeJS. NodeJS users can install them with npm
.
$ npm install @infostellarinc/stellarstation-api
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("stellarstation-private-key.json").openStream(),
URI.create("https://api.stellarstation.com"));
// Setup the gRPC client.
ManagedChannel channel =
ManagedChannelBuilder.forAddress("api.stellarstation.com", 443)
.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(
'stellarstation-private-key.json',
audience='https://api.stellarstation.com')
# Setup the gRPC client.
jwt_creds = google_auth_jwt.OnDemandCredentials.from_signing_credentials(
credentials)
channel = google_auth_transport_grpc.secure_authorized_channel(
jwt_creds, None, 'api.stellarstation.com:443')
client = stellarstation_pb2_grpc.StellarStationServiceStub(channel)
Other languages
Other languages have similar methods for loading Service Account JWT Access Credentials. For example,
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for stellarstation-0.8.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ab06be7f2349b97e487087318b81e48486aefb324d7a80133cdc8373512ad2b7 |
|
MD5 | f422e26968e5a004faf415983a3431f2 |
|
BLAKE2b-256 | 9d496a46e5c5601d8c8246c59654ace10afd339650f30253bd1da09fd54d758e |