Dokumentasi gRPC API

Apa itu gRPC?

gRPC adalah framework RPC (Remote Procedure Call) modern yang dikembangkan oleh Google. Berbeda dengan REST API yang menggunakan JSON, gRPC menggunakan Protocol Buffers sebagai format pertukaran data yang lebih efisien dan terstruktur.

Keunggulan gRPC:

• Performa Tinggi — Serialisasi data biner yang lebih cepat dan efisien daripada JSON
• Strongly-typed — Kontrak API yang jelas dengan .proto files
• Bandwidth Kecil — Mengurangi penggunaan bandwidth dengan kompresi data
• Streaming — Mendukung streaming unary, server, client, dan bidirectional

Protobuf Definition

Berikut adalah definisi Protocol Buffer yang digunakan oleh LokaID:

syntax = "proto3";

package lokaid;

service Address {
  rpc GetStates(Empty) returns (StatesResponse);
  rpc GetState(StateRequest) returns (StateResponse);
  rpc GetCities(StateRequest) returns (CitiesResponse);
  rpc GetCity(CityRequest) returns (CityResponse);
  rpc GetDistricts(CityRequest) returns (DistrictsResponse);
  rpc GetDistrict(DistrictRequest) returns (DistrictResponse);
  rpc GetVillages(DistrictRequest) returns (VillagesResponse);
  rpc GetVillage(VillageRequest) returns (VillageResponse);
}

message Empty {}

message Region {
  string code = 1;
  string value = 2;
}

message StateRequest {
  string code = 1;
}

message CityRequest {
  string code = 1;
}

message DistrictRequest {
  string code = 1;
}

message VillageRequest {
  string code = 1;
}

message StatesResponse {
  int32 status = 1;
  string message = 2;
  repeated Region data = 3;
}

message StateResponse {
  int32 status = 1;
  string message = 2;
  Region data = 3;
}

message CitiesResponse {
  int32 status = 1;
  string message = 2;
  repeated Region data = 3;
}

message CityResponse {
  int32 status = 1;
  string message = 2;
  Region data = 3;
}

message DistrictsResponse {
  int32 status = 1;
  string message = 2;
  repeated Region data = 3;
}

message DistrictResponse {
  int32 status = 1;
  string message = 2;
  Region data = 3;
}

message VillagesResponse {
  int32 status = 1;
  string message = 2;
  repeated Region data = 3;
}

message VillageResponse {
  int32 status = 1;
  string message = 2;
  Region data = 3;
}

Menggunakan gRPC API

Untuk menggunakan gRPC API LokaID, ikuti langkah-langkah berikut:

1. Setup Client

Pertama, simpan definisi Protocol Buffer di atas ke file lokaid.proto. Kemudian, generate kode client menggunakan protoc untuk bahasa pemrograman yang kamu gunakan.

2. Endpoint

Endpoint gRPC LokaID:

https://lokaid.gilangpratama.id/grpc/

3. Contoh Kode (Node.js)

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

// Load protobuf
const packageDefinition = protoLoader.loadSync('lokaid.proto', {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
});

const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
const lokaid = protoDescriptor.lokaid;

// Membuat gRPC client
const client = new lokaid.Address(
  'lokaid.gilangpratama.id/grpc',
  grpc.credentials.createSsl()
);

// Mendapatkan daftar provinsi
client.getStates({}, (err, response) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(response.data);
});

// Mendapatkan daftar kota di provinsi tertentu
client.getCities({ code: '31' }, (err, response) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(response.data);
});

Metode Tersedia

• GetStates(Empty) — Mendapatkan daftar semua provinsi
• GetState(StateRequest) — Mendapatkan detail provinsi berdasarkan kode
• GetCities(StateRequest) — Mendapatkan daftar kota/kabupaten dalam provinsi
• GetCity(CityRequest) — Mendapatkan detail kota/kabupaten berdasarkan kode
• GetDistricts(CityRequest) — Mendapatkan daftar kecamatan dalam kota/kabupaten
• GetDistrict(DistrictRequest) — Mendapatkan detail kecamatan berdasarkan kode
• GetVillages(DistrictRequest) — Mendapatkan daftar desa dalam kecamatan
• GetVillage(VillageRequest) — Mendapatkan detail desa berdasarkan kode

gRPC API Documentation

What is gRPC?

gRPC is a modern RPC (Remote Procedure Call) framework developed by Google. Unlike REST APIs that use JSON, gRPC uses Protocol Buffers as a more efficient and structured data exchange format.

Advantages of gRPC:

• High Performance — Binary data serialization that is faster and more efficient than JSON
• Strongly-typed — Clear API contracts with .proto files
• Low Bandwidth — Reduces bandwidth usage with data compression
• Streaming — Supports unary, server, client, and bidirectional streaming

Using the gRPC API

To use the LokaID gRPC API, follow these steps:

1. Client Setup

First, save the Protocol Buffer definition above to a file named lokaid.proto. Then, generate client code using protoc for the programming language you're using.

2. Endpoint

Endpoint gRPC LokaID:

https://lokaid.gilangpratama.id/grpc/

3. Example Code (Node.js)

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

// Load protobuf
const packageDefinition = protoLoader.loadSync('lokaid.proto', {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
});

const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
const lokaid = protoDescriptor.lokaid;

// Create gRPC client
const client = new lokaid.Address(
  'lokaid.gilangpratama.id/grpc',
  grpc.credentials.createSsl()
);

// Get list of provinces
client.getStates({}, (err, response) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(response.data);
});

// Get list of cities in a province
client.getCities({ code: '31' }, (err, response) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(response.data);
});

Available Methods

• GetStates(Empty) — Get a list of all provinces
• GetState(StateRequest) — Get province details by code
• GetCities(StateRequest) — Get list of cities/regencies in a province
• GetCity(CityRequest) — Get city/regency details by code
• GetDistricts(CityRequest) — Get list of districts in a city/regency
• GetDistrict(DistrictRequest) — Get district details by code
• GetVillages(DistrictRequest) — Get list of villages in a district
• GetVillage(VillageRequest) — Get village details by code