Indexed by TopGit from live GitHub metadata: slackhq/EitherNet has 792 stars, written primarily in Kotlin. A multiplatform, pluggable, and sealed API result type for modeling network API responses.
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
A multiplatform, pluggable, and sealed API result type for modeling network API responses. Currently, this is
only implemented for Retrofit on the JVM, but the core API is defined in
common code and can be implemented for other platforms/frameworks.
The rest of the README below focuses on the Retrofit implementation.
Usage
By default, Retrofit uses exceptions to propagate any errors. This library leverages Kotlin sealed types
to better model these responses with a type-safe single point of return and no exception handling needed!
The core type for this is ApiResult<out T, out E>, where T is the success type and E is a possible
error type.
ApiResult has two sealed subtypes: Success and Failure. Success is typed to T with no
error type and Failure is typed to E with no success type. Failure in turn is represented by
four sealed subtypes of its own: Failure.NetworkFailure, Failure.ApiFailure, Failure.HttpFailure,
and Failure.UnknownFailure. This allows for simple handling of results through a consistent,
non-exceptional flow via sealed when branches.
when (val result = myApi.someEndpoint()) {
is Success -> doSomethingWith(result.response)
is Failure -> when (result) {
is NetworkFailure -> showError(result.error)
is HttpFailure -> showError(result.code)
is ApiFailure -> showError(result.error)
is UnknownFailure -> showError(result.error)
}
}
Usually, user code for this could just simply show a generic error message for a Failure
case, but the sealed subtypes also allow for more specific error messaging or pluggability of error
types.
Simply change your endpoint return type to the typed ApiResult and include our call adapter and
delegating converter factory.
interface TestApi {
@GET("/")
suspend fun getData(): ApiResult<SuccessResponse, ErrorResponse>
}
val api = Retrofit.Builder()
.addConverterFactory(ApiResultConverterFactory)
.addCallAdapterFactory(ApiResultCallAdapterFactory)
.build()
.create<TestApi>()
If you don't have custom error return types, simply use Unit for the error type.
Decoding Error Bodies
If you want to decode error types in HttpFailures, annotate your endpoint with @DecodeErrorBody:
Now a 4xx or 5xx response will try to decode its error body (if any) as ErrorResponse. If you want to
contextually decode the error body based on the status code, you can retrieve a @StatusCode annotation
from annotations in a custom Retrofit Converter.
// In your own converter factory.
override fun responseBodyConverter(
type: Type,
annotations: Array<out Annotation>,
retrofit: Retrofit
): Converter<ResponseBody, *>? {
val (statusCode, nextAnnotations) = annotations.statusCode()
?: return null
val errorType = when (statusCode.value) {
401 -> Unauthorized::class.java
404 -> NotFound::class.java
// ...
}
val errorDelegate = retrofit.nextResponseBodyConverter<Any>(this, errorType.toType(), nextAnnotations)
return MyCustomBodyConverter(errorDelegate)
}
Note that error bodies with a content length of 0 will be skipped.
Plugability
A common pattern for some APIs is to return a polymorphic 200 response where the data needs to be
dynamically parsed. Consider this example:
{
"ok": true,
"data": {
...
}
}
The same API may return this structure in an error event
This is hard to model with a single concrete type, but easy to handle with ApiResult. Simply
throw an ApiException with the decoded error type in a custom Retrofit Converter and it will be
automatically surfaced as a Failure.ApiFailure type with that error instance.
@GET("/")
suspend fun getData(): ApiResult<SuccessResponse, ErrorResponse>
// In your own converter factory.
class ErrorConverterFactory : Converter.Factory() {
override fun responseBodyConverter(
type: Type,
annotations: Array<out Annotation>,
retrofit: Retrofit
): Converter<ResponseBody, *>? {
// This returns a `@ResultType` instance that can be used to get the error type via toType()
val (errorType, nextAnnotations) = annotations.errorType() ?: return null
return ResponseBodyConverter(errorType.toType())
}
class ResponseBodyConverter(
private val errorType: Type
) : Converter<ResponseBody, *> {
override fun convert(value: ResponseBody): String {
if (value.isErrorType()) {
val errorResponse = ...
throw ApiException(errorResponse)
} else {
return SuccessResponse(...)
}
}
}
}
Retries
A common pattern in making network requests is to retry with exponential backoff. EitherNet ships with a highly configurable retryWithExponentialBackoff() function for this case.
// Defaults for reference
val result = retryWithExponentialBackoff(
maxAttempts = 3,
initialDelay = 500.milliseconds,
delayFactor = 2.0,
maxDelay = 10.seconds,
jitterFactor = 0.25,
onFailure = null, // Optional Failure callback for logging
) {
api.getData()
}
Testing
EitherNet ships with a Test Fixtures
artifact containing a EitherNetController API to allow for easy testing with EitherNet APIs. This
is similar to OkHttp’s MockWebServer, where results can be enqueued for specific endpoints.
Simply create a new controller instance in your test using one of the newEitherNetController() functions.
val controller = newEitherNetController<PandaApi>() // reified type
Then you can access the underlying faked api property from it and pass that on to whatever’s being tested.
// Take the api instance from the controller and pass it to whatever's being tested
val provider = PandaDataProvider(controller.api)
Finally, enqueue results for endpoints as needed.
// Later in a test you can enqueue results for specific endpoints
controller.enqueue(PandaApi::getPandas, ApiResult.success("Po"))
You can also optionally pass in full suspend functions if you need dynamic behavior
controller.enqueue(PandaApi::getPandas) {
// This is a suspend function!
delay(1000)
ApiResult.success("Po")
}
In instrumentation tests with DI, you can provide the controller and its underlying API in a test
module and replace the standard one. This works particularly well with Anvil.
@ContributesTo(
scope = UserScope::class,
replaces = [PandaApiModule::class] // Replace the standard module
)
@Module
object TestPandaApiModule {
@Provides
fun providePandaApiController(): EitherNetController<PandaApi> = newEitherNetController()
@Provides
fun providePandaApi(
controller: EitherNetController<PandaApi>
): PandaApi = controller.api
}
Then you can inject the controller in your test while users of PandaApi will get your test instance.
Java Interop
For Java interop, there is a limited API available at JavaEitherNetControllers.enqueueFromJava.
Validation
EitherNetController will run some small validation on API endpoints under the hood. If you want to
add your own validations on top of this, you can provide implementations of ApiValidator via
ServiceLoader. See ApiValidator's docs for more information.
Installation
dependencies {
implementation("com.slack.eithernet:eithernet:<version>")
implementation("com.slack.eithernet:eithernet-integration-retrofit:<version>")
// Test fixtures
testImplementation("com.slack.eithernet:eithernet-test-fixtures:<version>")
}
Snapshots of the development version are available in Sonatype's snapshots repository.
License
Copyright 2020 Slack Technologies, LLC
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
The most recent commit recorded on slackhq/EitherNet was 2 months ago, based on the GitHub push timestamp. The repository has 28 forks — one of the better signals of community interest.
How does slackhq/EitherNet compare to other Backend projects?
slackhq/EitherNet is tracked by TopGit in the Backend category, with 792 GitHub stars and written in Kotlin. Browse the Backend topic page on TopGit to compare it against similar projects by stars and activity.
How many stars does slackhq/EitherNet have?
slackhq/EitherNet has 792 GitHub stars — refresh the page for the live number, or check github.com/slackhq/EitherNet. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
What is slackhq/EitherNet?
slackhq/EitherNet (slackhq/EitherNet) is a Kotlin project on GitHub. From the project's own README: A multiplatform, pluggable, and sealed API result type for modeling network API responses.
What language is slackhq/EitherNet written in?
slackhq/EitherNet is written primarily in Kotlin. GitHub's language field is based on the largest share of bytes in the default branch.
What topics is slackhq/EitherNet associated with?
GitHub's repository topics for slackhq/EitherNet: "java", "kotlin", "multiplatform", "okhttp", "retrofit". TopGit's editorial category is Backend.
Why is slackhq/EitherNet categorized under Backend?
TopGit places slackhq/EitherNet in the Backend category based on its GitHub topics and description (tagged: "java", "kotlin", "multiplatform"). Categories are assigned from real repository metadata, not editorial guesswork.
Read full README in the tab above.
Want a second opinion on EitherNet?
Ask an AI that can read this page — one click and you get its take on EitherNet.
/EitherNet