Getting Started

Getting Started#

Requirements#

This guide requires curl and grpcurl to be installed. grpcurl will require the Protobuf definitions of the Ridepooling API as input which we provide as a zip archive. The zip archive includes:

  • Protobuf definitions of the Ridepooling API,

  • Common types used in the Ridepooling API.

You can download the zip archive here: ridepooling_api.zip.

For later usage, unzip the zip archive e.g:

unzip ./ridepooling_api.zip -d .

Getting Access#

The Ridepooling API is only available to Integrators. If you are interested in becoming an Integrator, please contact us.

After your registration was processed, MOIA will provision credentials for evaluating / integrating with the Ridepooling API product.

Note

Evaluation Credentials Evaluation credentials are valid for a limited time period and will allow testing of the Ridepooling API. With evaluation credentials you can immediately get started, following these steps.

Setup Credentials#

Retrieve the API token using the following request providing the credentials using the Authorization header. Replace $CLIENT_ID and $CLIENT_SECRET with the credentials provided.

curl \
--http2 \
--request POST \
--location "https://ridepooling-api.int.eu-central-1.moia-group.io/auth/oauth/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--user "$CLIENT_ID:$CLIENT_SECRET" \
--data-urlencode "grant_type=client_credentials"

You will need an <ACCESS_TOKEN> for all subsequent requests. Set the token as an environment variable for convenience in the following steps. Replace <ACCESS_TOKEN> with the token you received through authentication, in the previous step.

export ACCESS_TOKEN=<ACCESS_TOKEN>

Note

Authentication Problems In cases when a 401 error is repeatedly returned, please retry the Authentication steps. If this problem persists, please contact us as there may be a problem with your credentials.

Structure of Basic API Call#

To place an API call with grpcurl set the following options:

  1. Provide the Bearer token for authorization in the header with -H "Authorization: Bearer <ACCESS_TOKEN>

  2. Only for customer-scope endpoints: Provide the Customer ID in the metadata with -H "Customer-Id: <CUSTOMER_ID>"

  3. Provide the paths in which the protobuf definitions are located, e.g. -import-path <PATH_TO_RIDEPOOLING_API_PROTOS>. Make sure that all required definitions are located at this path.

  4. Provide the JSON formatted request data with -d '<JSON_FORMATTED_REQUEST>'

  5. State the name of the protobuf source file for the corresponding gRPC service:

    • -proto moia/ridepooling/trip/v1beta2/trip.proto for Trip Service

  6. For convenience, set -emit-defaults to show default values in the responses.

Taking into considerations all of the above, this represents a sample grpcurl command:

# export OFFER_TOKEN="<replace with token>"

grpcurl \
  -H "authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Customer-Id: ${CUSTOMER_ID}" \
  -import-path ./protos/ \
  -proto "moia/ridepooling/trip/v1beta2/trip.proto" \
  -d "{\"offer_token\":\"$OFFER_TOKEN\"}" \
  ridepooling-api.int.eu-central-1.moia-group.io:443 moia.ridepooling.trip.v1beta2.TripService/OrderTrip

Note

TLS

Ridepooling API uses TLS for transport encryption. grpcurl enables TLS by default. If you use another client to evaluate the API make sure TLS is enabled.