@adapt2move/common-java v0.0.1

openapi-java-client

Adapt2Move-API

• API version: 1.0.0
  • Build date: 2024-02-18T20:41:28.001989900+01:00Europe/Berlin

Getting Started with Adapt2Move

The Adapt2Move API aims to provide general information about Mobility Service Providers (MSPs) and their available Mobility Options, including the ability to make bookings, get support and so on. Mobility Service Providers (MSPs) can offer Mobility Options such as Carsharing, Carrental or Bikesharing. The API is divided into Service category endpoints, which provide general information about MSPs, and MSP-specific endpoints, which address a specific MSP (\"Token adapter\", \"Search adapter\", \"Booking adapter\").

The Adapt2Move API is designed for integration with B2B software vendors. Get in touch with us to get support and provide the best user experience for your customers.

Authentification (via Token-Adapter)

All endpoints require authentication using an API key that you send in the header (name: Ocp-Apim-Subscription-Key) and that is associated with your particular subscription and customer. Each of your customers will have their own API key, which you can create in our Developer Portal. To create an API key, select a new subscription that meets your customer's requirements. A contract with Adapt2Move is always required to activate the subscription. Free developer subscriptions and limited scope free subscriptions are available. Most MSP specific endpoints require additional authentication in the form of a token. Adapt2Move does not interfere with the relationship and contract between the enterprise requesting mobility and the MSP. In order to utilize the services of a supported MSP, the customer (organization or enterprise) must contract directly with the MSP and agree to individual terms and conditions. The customer then receives their credentials. They can then obtain their token for authentication via the Adapt2Move Token Adapter. The Token-Adapter currently only has a single endpoint that serves exactly this purpose, but more might be added in the future to support a bigger variety of authentication and authorization schemes. We are trying to map as many schemes down to the generation of a secure and non-permanent session token that can be used for the Booking-API. Tokens that are created using the Token-API are always non-permanent. They expire at a given moment in the future after which they no longer can be used. A new token however can be created at any point in time, even if there is another one that has not yet expired.

MSP Login Implementation Sequence Diagram

Service (General)

Use of the Service Endpoints is possible with the Adapt2Move API Token only. The Service Endpoints allow for querying Adapt2Move for the mobility service providers (MSP) that are available through it in general. This endpoint can be used for regular downloads of the most recent list of available MSPs or queried just before requests for a particular mobility demand are about to happen. Each MSP in the list contains an apiBaseUrl property that must be used to query the service for mobility and booking information. All the other APIs listed above are available on this base URL for each MSP. If, for example, a particular connection is demanded, starting from a known location and ending at a known location, there might be multiple MSPs that could be able to satisfy the demand. To get mobility options from each of those, the same request for mobility options must be sent to each MSP individually using their base URL with the corresponding endpoint, in this case, the \"options\" endpoint. Each of the MSPs will then return with options to satisfy the mobility demand using their mobility service. Querying each of the MSPs individually, instead of bundling them together in a single HTTP request, allows for faster MSPs to return their results quicker than slower ones which can contribute very much to the user experience of users.

Search Adapter (MSP-specific)

The Search Adapter also targets a specific MSP and provides information about the locations of stations or vehicles, etc. In most cases, the MSP will require authentication. To do this, send the token you received. Places are objects that usually have a fixed geolocation but are somehow related to the mobility service of the MSP. This could e.g. be the train and bus stations of a local public traffic provider or the stations at which rental cars can be obtained or returned. Though this is currently not yet supported, we might add the possibility to query place-specific information like timetables for bus lines or opening hours in a coming version. Vehicles are objects that are used for moving. Besides many properties that describe the vehicle and its capabilities, they have a geolocation that frequently changes and they are part of a booking most of the time. Options are objects that represent mobility \"options\", which mean specific possibilities of moving and traveling according to the specific demands of a user. They can represent full traveling connections with start and end point, start and or ent time including the traveling legs with transit points and vehicles being used in each leg, just as well as simple free-floating vehicles being nearby, ready to be used from where the user is currently standing, even if the end location and time are not yet known. Of particular interest in the Search-Adapter is the Options endpoint. It provides many filter criteria that can be used to narrow down the possible options for a particular mobility demand.

Get Options Implementation Sequence Diagram

Booking Adapter (MSP-specific)

The Booking-Adapter serves all tasks required for creating and managing bookings. Bookings are created using a BookingRequest object populated with the information provided in an Option as is but extended with additional information about the passengers that are going to use the Option. A Booking has a lifecycle that is described in the Booking object of the specification. If the Option from which the Booking is created has the flag startsImmediately set to true, then the Booking will immediately start after requesting it and thus be in state STARTED. For options that had the particular flag set to false the booking created from them will initially be in state BOOKED. The state of a Booking is always dictated by the MSP. Changes to the state can happen due to changes by the MSP, due to progress in time, e.g. when the start moment of a booking has passed, or through booking actions available to the user. Each booking object contains a list of actions that can be taken on it, which also includes actions that transition the state of a booking from one to another. The possibilities to transition the state are defined in the specification.

MSP Login Implementation Sequence Diagram

For more information, please visit https://www.adapt2move.de/kontakt/

Automatically generated by the OpenAPI Generator

Requirements

Building the API client library requires: 1. Java 1.8+ 2. Maven (3.8.3+)/Gradle (7.2+)

Installation

To install the API client library to your local Maven repository, simply execute:

mvn clean install

To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:

mvn clean deploy

Refer to the OSSRH Guide for more information.

Maven users

Add this dependency to your project's POM:

<dependency>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-java-client</artifactId>
  <version>1.0.0</version>
  <scope>compile</scope>
</dependency>

Gradle users

Add this dependency to your project's build file:

  repositories {
    mavenCentral()     // Needed if the 'openapi-java-client' jar has been published to maven central.
    mavenLocal()       // Needed if the 'openapi-java-client' jar has been published to the local maven repo.
  }

  dependencies {
     implementation "org.openapitools:openapi-java-client:1.0.0"
  }

Others

At first generate the JAR by executing:

mvn clean package

Then manually install the following JARs:

• target/openapi-java-client-1.0.0.jar
• target/lib/*.jar

Getting Started

Please follow the installation instruction and execute the following Java code:

// Import classes:
import org.openapitools.client.ApiClient;
import org.openapitools.client.ApiException;
import org.openapitools.client.Configuration;
import org.openapitools.client.auth.*;
import org.openapitools.client.models.*;
import org.openapitools.client.api.BookingAdapterMspSpecificApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("https://adapt2-move-api-management.azure-api.net/v1.0");
    
    // Configure API key authorization: ApiKeyAuth
    ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
    ApiKeyAuth.setApiKey("YOUR API KEY");
    // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
    //ApiKeyAuth.setApiKeyPrefix("Token");

    BookingAdapterMspSpecificApi apiInstance = new BookingAdapterMspSpecificApi(defaultClient);
    String mspId = "fake-msp"; // String | Human-readable and unique Id of the particular MSP. indicates the endpoint for this  MSP received from `MobilityServiceProvider.id`
    String mspToken = "mspToken_example"; // String | Enter the `TokenResponse.token` received from Token-Adapter. The MSP itself decides which request requires a token.
    BookingRequest bookingRequest = new BookingRequest(); // BookingRequest | 
    try {
      Booking result = apiInstance.createNewBooking(mspId, mspToken, bookingRequest);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling BookingAdapterMspSpecificApi#createNewBooking");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Documentation for API Endpoints

All URIs are relative to https://adapt2-move-api-management.azure-api.net/v1.0

Documentation for Models

• ArealMandate
• ArealMandateEnum
• ArealMap
• Asset
• AssetRestriction
• Booking
• BookingAction
• BookingRequest
• BookingState
• ContactInfo
• ContactPerson
• Coordinates
• Error
• GeoArea
• GeoAreaType
• GeoCircle
• GeoPolygon
• Leg
• LinkResult
• LinkResultResult
• LinkResultType
• Marketing
• MarketingColor
• MobilityServiceProvider
• Mode
• MoneyValue
• Option
• Passenger
• Place
• Propulsion
• StandardCredentials
• TokenResponse
• Vehicle
• VehicleAction

Documentation for Authorization

Authentication schemes defined for the API:

ApiKeyAuth

• Type: API key
• API key parameter name: Ocp-Apim-Subscription-Key
• Location: HTTP header

Recommendation

It's recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.

Author

info@adapt2move.de