com.avonfitzgerald:infinitelive

InfiniteLiveKt

Fast-track development with the Infinite Flight Live API.

InfiniteLiveKt's main objective is to provide a safe way of handling the API through Kotlin's strong type system. Thus, no exceptions are thrown and any signatures properly describe the behaviour of any function. This is accomplished using the Λrrow library and its Either class.

Additionally, the InfiniteLiveKt library provides implementations of all publicly defined models and endpoints of the Infinite Flight Live API.

Setup

Gradle

Add dependencies in your build.gradle.kts file:

dependencies {
    implementation("com.avonfitzgerald:infinitelive:2.1.1")
}

Make sure Maven Central is in your list of repositories:

repositories {
    mavenCentral()
}

Maven

Add dependencies in your pom.xml file:

<dependency>
  <groupId>com.avonfitzgerald</groupId>
  <artifactId>infinitelive</artifactId>
  <version>2.1.1</version>
</dependency>

Getting Started

Basic Configuration

Before anything else, you will need to have a valid API Key to access the Infinite Flight Live API. Details on how to obtain your key are available in the official documentation.

First things first, you will need to instantiate InfiniteLive with your API key.

fun main() {
    val live = InfiniteLive(INFINITE_FLIGHT_API_KEY)
}

By default, InfiniteLive will use an HttpClient from Ktor with the CIO engine. You can change the engine by passing your preferred client as the second parameter.

fun main() {
    val live = InfiniteLive(INFINITE_FLIGHT_API_KEY, HttpClient(OkHttp))
}

If you are configuring your own engine do not forget to include the relevant dependencies.

Handling Requests

InfiniteLive has two available methods to make HTTPS requests to the API :

suspend fun <T> getRequest(endpoint: Get<T>): Either<Throwable, T>
suspend fun <T> postRequest(endpoint: Post<T>): Either<Throwable, T>

T is the generic type of your object of interest after deserialization of the JSON response from the API. This object can be a session/server, a flight, a list of airports or anything else.

Get and Post are both aliases of InfiniteLiveEndpoint.Get and InfiniteLiveEndpoint.Postrespectively. They both inherit from the sealed class InfiniteLiveEndpoint.

Naturally, as the library performs network calls, it enforces the use of Kotlin Coroutines as both methods are marked as suspend.

When you use either of these methods, it will execute the following instructions:

1. Fetch JSON data from the API. If it fails, send back an Either.Left containing the error.

2. Check if the JSON is in the correct format with an internal error code and an appropriate result. If it fails, send back an Either.Left containing a MalformedResponse exception (more info about error handling below) with the HTTP Status Code and the raw response from the server.

3. Check if the Infinite Flight API responded with an OK internal error code. If it fails, send back an Either.Left containing an InfiniteLiveException with the serialized message.

4. Perform the deserialization to obtain an Either.Right containing the deserialized object T defined in the InfiniteLiveEndpoint. If it fails, send back an Either.Left containing the error.

Error Handling

When you perform a request there are a multitude of ways your code might fail. Thankfully, with the help of functional programming we can appropriately handle them whenever an error occurs, thus avoiding unexpected failures which may cause a fatal crash.

There are two major type of exceptions you need to be aware of :

• InfiniteLiveException
• Exception

With Either handling errors becomes a trivial matter, and you can write proper fault-tolerant code.

Example:

suspend fun getAtis(sessionId: String, airportIcao: String): String = live.getRequest(
   GetAirportAtis(sessionId, airportIcao)
).mapLeft {
   when (it) {
      is NoAtisAvailable -> "ATIS is not available"
      is InfiniteLiveException -> "Infinite Flight Failure"
      else -> "Internal Server Error"
   }
}.merge()

InfiniteLiveException

This exception occurs if the Infinite Flight Live API has responded with an invalid or valid JSON response. All exceptions inheriting from InfiniteLiveException have defined aliases (e.g. typealias MalformedResponse = InfiniteLiveException.MalformedResponse)

Invalid JSON (no errorCode or result field in the raw JSON response):

• MalformedException (includes the properties httpStatusCode and body)

Valid JSON:

• UserNotFound
• MissingRequestParameters
• EndpointError
• NotAuthorized
• ServerNotFound
• FlightNotFound
• NoAtisAvailable
• AirportNotFound
• UndefinedErrorCode (includes the properties errorCode and result serialized)

Exception (Not InfiniteLiveException)

This exception occurs if something went wrong on your side such as a network error (e.g. not connected to the internet), JSON deserialization error or else.

Predefined Get/Post Requests

The InfiniteLiveKt library provides implementations of all publicly defined models and endpoints of the Infinite Flight Live API :

• GetSessions
• GetFlights
• GetFlightRoute
• GetFlightPlan
• GetActiveAtcFrequencies
• PostUserStats
• GetUserGrade
• GetAirportAtis
• GetAirportStatus
• GetWorldStatus
• GetOceanicTracks
• GetUserFlights
• GetUserFlight
• GetUserAtcSessions
• GetUserAtcSession
• GetNotams
• GetAircraft
• GetAircraftLiveries
• GetAllLiveries

Example:

suspend fun printFlightsFromServer(serverId: String): Either<Throwable, Unit> = either {
   val flights = live.getRequest(GetFlights(serverId)).bind()
   flights.forEach(::println)
}

Predefined endpoints from InfiniteLiveKt do not deserialize deprecated fields from the Infinite Flight Live API and do not fall back to default values except for enums (they will default to their associated INVALID field).

Custom Get/Post Requests

If somehow an endpoint is missing, or you want to provide your own deserialization strategy you can define a custom InfiniteLiveEndpoint. To do so, simply inherit from Get (alias of InfiniteLiveEndpoint.Get) or Post (alias of InfiniteLiveEndpoint.Post) depending on the HTTPS request. The Infinite Flight Live API does not use other HTTP methods such as PUT or DELETE.

Example (Get):

class GetSessions : Get<List<SessionInfo>>("sessions") {
    override fun deserialize(data: String): List<SessionInfo> = Json.decodeFromString(data)
}

Example (Post):

// Fictitious endpoint for the purpose of the example
class PostRequest(serializedJson: String) : Post<SomeObject>("some-post", serializedJson) {
    override fun deserialize(data: String): List<SomeObject> = Json.decodeFromString(data)
}

License

MIT License : Copyright (c) 2022 Avon FitzGerald