api

API - the gRPC client for earthquakes

A gRPC client (written in Dart) for accessing earthquake data from the quake gRPC service (written in Go).

This is a Dart code project named api under the quake_monitor repository. The repository contains also other Dart and Flutter projects.

Dependencies

gRPC message and service definitions as Protocol Buffers schema:

• under the quake repository
  • api/v1/quake.proto for message definitions
  • api/v1/quake_api.proto for the service definition

The client containing both generated and written Dart code depends also on following external packages:

• fixnum
• protobuf
• grpc

Please see pubscec.yaml for more details and versions used.

Usage

EarthquakeApiClient class in the api/lib/src/helper/api_client.dart source file wraps setting up a gRPC channel for the server and calling it.

A basic example for using the class to get earthquake list from a local server:

  // setup API client and open a channel to gRPC service
  final client = EarthquakeApiClient(
      address: "localhost", port: 50051, isSecure: false);
  final channel = await client.open();
  try {
    // call gRPC service
    final col = await channel.listEarthquakes(
        magnitude: Magnitude.MAGNITUDE_SIGNIFICANT,
        past: Past.PAST_7DAYS,
        limit: 10,
        details: false);

    if (col != null) {
      for (Earthquake eq in col.features) {
        // do something with an earthquake iterated from a resulting collection
      }
    }
  } finally {
    // ensure resources are closed  
    await channel.shutdown();
  }

Testing

The quake_client is a simple CLI command to test a gRPC service and it has a main() function in the api/bin/quake_client.dart source file. This uses also the EarthquakeApiClient class introduced above.

Please ensure you have Dart SDK (minimum version 2.7) installed on your system.

Then under a local repository clone you can run the test client:

$ dart api/bin/quake_client.dart help

By default the client accesses localhost server address at the port 50051. This can be modified by setting a QUAKE_SERVICE environment variable for a server address and port (ie. myserver.example.org:443).

Some examples for requesting earthquakes from a gRPC service using command line:

$ dart api/bin/quake_client.dart ListEarthquakes significant 7days
$ dart api/bin/quake_client.dart ListEarthquakes 2.5 day 5 

Code generation

This project contains generated .dart files for server interface code and client side stubs related to the gRPC service defined on the quake repository introduced earlier.

If you like or need to regenerate server interfaces and client stubs for Dart then you need a development environment with following command line tools:

• protoc (Protocol Buffer v3)
• protoc-gen-dart (protoc compiler extension for Dart)

Please consult following quick start quide to setup your environment first:

• Dart Quick Start for gRPC

When needing regeneration then on your development enviroment cd to the api folder and run make command to generate Dart code. Generated code is stored on the the api/lib/src/quake/api/v1 folder.

This process is defined on the Makefile. Please note that it assumes that you have following repositories locally under the same root:

• quake
  • api/v1 (proto files here)
• quake_monitor
  • api (this project)
    • Makefile (use this to make code generation)
    • lib/src/quake/api/v1 (dart code is generated here)

Authors

This project is authored by Navibyte.

License

This project is licensed under the MIT License - see the LICENSE.