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:1.0.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>1.0.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 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.Post
respectively.
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:
-
Fetch JSON data from the API. If it fails, send back an Either.Left containing the error.
-
Check if the JSON is in the correct format with an internal error code and an appropriate result from the API. If it fails, send back an Either.Left containing a
MalformedResponse
exception (error handling are described below in the README) with the HTTP Status Code and the raw response from the server. -
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. -
Perform the deserialization to obtain an Either.Right containing the deserialized object
T
defined in theInfiniteLiveEndpoint
. 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.
They 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
- UndefinedErrorCode (includes the properties errorCode and result serialized)
Exception
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
Example:
suspend fun printFlightsFromServer(serverId: String): Either<Throwable, Unit> = either {
val flights = live.getRequest(GetFlights(serverId)).bind()
flights.forEach(::println)
}
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 HTTPS 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