API Concepts

API Concepts#

Pagination#

We use Pagination for all our List endpoints. You can optionally pass a page_size parameter in the request to limit the amounts of items returned.

Example output:

{
  "trips": [
    {
      "id": "94d36e21-ca69-4a5b-b2b7-8068122e7362"
    },
    {
      "id": "76350d1a-8df5-4217-8d58-207f4e1e0b90"
    }
  ],
  "nextPageToken": "c688a598-9a67-4dde-b2b3-98992a051bb0"
}

To query the next page use the returned page token with c688a598-9a67-4dde-b2b3-98992a051bb0 and include it in the next request.

Versioning#

The Ridepooling API adopts a continuous release model to provide our users with rapid access to product innovation, enhancements and security patches, while maintaining the highest level of quality. The API consists of multiple services, each of which is versioned independently.

Release Cadence#

Announcements regarding releases will be made in the changelog.

Proto Package Versioning#

We version our API through proto package versioning and include the version number in the package name. Backwards compatibility is maintained within the same version of a package. When a breaking change is introduced, a new version of the package is created.

All changes will be reported in the changelog regardless if they are breaking or not.

Non-Breaking Changes#

These changes are non-breaking at gRPC protocol level and binary level.

  • Adding a new Service

  • Adding a new RPC to an existing Service

  • Adding a new field to a request or response message

  • Adding a new enum value

  • Renaming a field

Binary Breaking Changes#

The following changes are non-breaking at a gRPC protocol level, but depending on the programming language used, they may be breaking at a binary level.

  • Removing a field

  • Renaming a Message

Protocol Breaking Changes#

The following changes are breaking at a gRPC protocol and binary level.

  • Removing a Service or RPC

  • Changing a field type

  • Changing a field number

  • Renaming a package, Service or RPC

Clients can import the specific version they want to use, and changes to the API can be introduced in a new version while maintaining support for the older version.

Support Policy#

We provide support for the current version of the Service and continuously update it with non-breaking changes. When breaking changes require the release of a new version, the previous version will be deprecated but continued to be supported for the period agreed upon in the contract. This allows users to upgrade to the newer version when it aligns with their business requirements. However, we strongly recommend using the latest version of the API to take advantage of the latest features and improvements.

Support means that a previous version will remain available and operational, and bug and security fixes will be provided.

Beta Versions#

Beta versions are not considered stable and while we try to avoid breaking changes within the same beta version, they may occur. We also do not guarantee that beta versions will be supported for the same duration as stable versions.

Errors#

The Ridepooling API uses gRPC richer error handling. The gRPC response codes indicate the success or failure of an API request. In addition, the Ridepooling API provides detailed error messages when applicable to assist in diagnosing issues. Commonly used error details are documented here.

For each RPC, service-specific errors and details are documented in the API Reference. Standard client and server errors (e.g. UNIMPLEMENTED, UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT, NOT_FOUND) are omitted in the API reference but applied for every RPC.

HTTP

Status (RPC Code)

Description

Error Details

200

OK (0)

Success.

400

INVALID_ARGUMENT (3)

Caller specified an invalid argument in request.

BadRequest detail for every invalid field.

400

FAILED_PRECONDITION (9)

Operation was rejected because the system is not in a state required for the operation’s execution.

400

OUT_OF_RANGE (11)

Operation was attempted past the valid range.

401

UNAUTHENTICATED (16)

The request does not have valid authentication credentials for the operation. Please check the Authentication guide for more information and retry the call with valid credentials.

403

PERMISSION_DENIED (7)

Caller does not have permission to execute the specified operation.

404

NOT_FOUND (5)

Requested entity (e.g. Trip or Customer) was not found.

ResourceInfo to provide details about resource which was not found, ErrorInfo if pagination token was not found.

409

ALREADY_EXISTS (6)

Attempt to create an entity failed because one already exists.

409

ABORTED (10)

Operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts etc.

429

RESOURCE_EXHAUSTED (8)

Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.

499

CANCELLED (1)

The operation was cancelled (typically by the caller).

500

UNKNOWN (2)

Unknown server error. Typically a server bug. Please report the bug.

500

INTERNAL (13)

Internal server error. Typically a server bug. Please report the bug.

500

DATA_LOSS (15)

Unrecoverable data loss or corruption.

501

UNIMPLEMENTED (12)

Operation is not implemented or not supported/enabled in this service.

503

UNAVAILABLE (14)

Service is currently unavailable. This is a most likely a transient condition and may be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations.

504

DEADLINE_EXCEEDED (4)

Operation expired before completion. Retry with increased timeout.

MOIA Common Types#

We use common types for messages that are used among multiple Services. If a Service uses common types, the API Reference lists all required protobuf definitions. All required protobuf definitions need to be included when invoking a method by specifying the import-path correctly. Detailed information about all common types is available in the API Reference.