Basic Client

Basic Client#

This guide provides a step-by-step walkthrough for setting up a basic client to interact with the Ridepooling API. Follow the instructions to authenticate and connect to the API in order to make requests. Some general gRPC and protobuf knowledge is recommended for working with this example.

Project setup#

Note

We are currently working on this section. New updates are coming soon.

Requires Node.js 12 or higher.

We will use buf to generate a TypeScript client for the Ridepooling API. The commands below will set up a new project and install the required dependencies.

  1. Download the protobuf definitions protos and create the project using the commands:

mkdir ridepooling-client-ts && cd ridepooling-client-ts
brew install protobuf
npm init -y
tsc --init
cp your-donwloads/protos .

  1. Create two files with the command touch buf.yaml buf.gen.yaml and use the following content for the files:

  • buf.yaml

version: v1
breaking:
  use:
    - FILE
lint:
  use:
    - DEFAULT
build:
  excludes: [ node_modules ]

  • buf.gen.yaml

version: v1
managed:
  enabled: true
plugins:
  - name: ts
    path: ./node_modules/ts-proto/protoc-gen-ts_proto
    out: .
    strategy: all
    opt:
      - outputServices=generic-definitions
      - outputServices=nice-grpc
      - esModuleInterop=true
      - useExactTypes=false
      - useDate=string

  1. Run the following commands to install some project dependencies and generate the client code:

npm install @bufbuild/buf nice-grpc ts-proto
npx buf dep update
npx buf generate

  1. Create the client file. We can use ts-node to quickly run our TypeScript code.

touch client.ts
npx ts-node client.ts

File structure#

Note

We are currently working on this section. New updates are coming soon.

import * as grpc from "nice-grpc";
import { TripServiceDefinition } from "./moia/ridepooling/trip/v1beta2/trip";

async function main() {
  // The code of the next steps goes here
}

main().catch(console.error);

Authenticate#

To authenticate, we need to obtain an access token from the API gateway. For more information on authentication see the Authentication section.

Note

We are currently working on this section. New updates are coming soon.

To obtain a token we will send an HTTP request to the token URL using the fetch API. We can also use an OAuth2 client, as long as you authenticate with the grant type client_credentials and use the Authorization header with the Basic scheme.

  const apiAddress = 'ridepooling-api.${process.env.STAGE}.eu-central-1.moia-group.io:443';
  const tokenUrl = 'https://' + apiAddress + '/auth/oauth/token';

  const clientId = process.env.CLIENT_ID;
  const clientSecret = process.env.CLIENT_SECRET;

  const authHeader = Buffer.from(`${clientId}:${clientSecret}`).toString(
    'base64'
  );
  
  const tokenRequest = new Request(tokenUrl, {
    headers: {
      Authorization: `Basic ${authHeader}`,
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: 'grant_type=client_credentials',
    method: 'POST',
  });
  
  const response = await fetch(tokenRequest);
  const tokenResponse = (await response.json()) as Record<string, any>;

  if (tokenResponse.error) {
    console.error(tokenResponse.error_description);
    return;
  }
  
  const accessToken = tokenResponse.access_token;

Connect to the API#

Note

We are currently working on this section. New updates are coming soon.

We use nice-grpc to set up a gRPC channel and client. We use the grpc.Metadata class to add the Authorization header to all of our gRPC requests.

  const clientFactory = grpc.createClientFactory();
  const channel = grpc.createChannel(
    apiAddress,
    grpc.ChannelCredentials.createSsl()
  );

  const client = clientFactory.create(TripServiceDefinition, channel, {
    '*': {
      metadata: new grpc.Metadata({
        Authorization: `Bearer ${accessToken}`,
      }),
    },
  });

Continue with the API Usage example where we will call some of the Ridepooling API methods.

Contents