A configurable api client based on Retrofit2 and RxJava2 for android
- Basic Usage
- Unwrap Response by KeyPath
- Unwrap Response by Wrapper Class
- Serial / Concurrent Calls
- Retry Interval / Exponential backoff
- Call Cancellation
- Mock Response
In your app level build.gradle :
dependencies {
implementation 'com.jaychang:simpleapiclient:2.3.0'
// if you use gson
implementation 'com.jaychang:simpleapiclient-jsonparser-gson:2.3.0'
// if you use moshi
implementation 'com.jaychang:simpleapiclient-jsonparser-moshi:2.3.0'
}Config the api client and use it to create your api.
interface GithubApi {
companion object {
fun create() : GithubApi =
SimpleApiClient.create {
baseUrl = "https://api.github.com"
defaultParameters = mapOf()
defaultHeaders = mapOf()
connectTimeout = TimeUnit.MINUTES.toMillis(1)
readTimeout = TimeUnit.MINUTES.toMillis(1)
writeTimeout = TimeUnit.MINUTES.toMillis(1)
logLevel = LogLevel.BASIC // default NONE
isMockResponseEnabled = true // default false
certificatePins = listOf(
CertificatePin(hostname = "api.foo.com", sha1PublicKeyHash = "0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33"),
CertificatePin(hostname = "api.bar.com", sha256PublicKeyHash = "fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9")
)
interceptors = listOf()
networkInterceptors = listOf()
httpClient = OkHttpClient.Builder().build() // your own http client
jsonParser = MoshiJsonParser()
errorClass = ApiError::class // should be conformed to SimpleApiError
errorMessageKeyPath = "meta.message"
errorHandler = { error ->
// you can centralize the handling of general error here
when (error) {
is AuthenticationError -> {...}
is ClientError -> {...}
is ServerError -> {...}
is NetworkError -> {...}
is SSLError -> {...}
}
}
}
}
@GET("/search/users")
fun getUsers(@Query("q") query: String): Single<List<User>>
}Use observe() to enqueue the call, do your stuff in corresponding parameter block. All blocks are run on android main thread by default and they are optional.
githubApi.getUsers("google")
.observe(
onStart = { println("show loading") },
onEnd = { println("hide loading") },
onSuccess = { println(it) },
onError = { println(it.message) }
)Sometimes the api response includes metadata that we don't need, but in order to map the response we create a wrapper class and make the function return that wrapper class. This approach leaks the implementation of service to calling code.
Assuming the response json looks like the following:
{
total_count: 33909,
incomplete_results: false,
foo: {
bar: {
items: [
{
login: "jaychang0917",
...
}
...
]
}
}
}And you only want the items part, use @KeyPathResponse("keypath") annotation to indicate which part of response you want.
@GET("/search/users")
@KeyPathResponse("foo.bar.items")
fun getUsers(@Query("q") query: String): Single<List<User>>Similarly, unwrap the error response by setting the errorMessageKeyPath of SimpleApiClient.Config
An alternative solution is that you can create a wrapper class that conforming SimpleApiResult<T>, and use @WrappedResponse(class) to indicate that you want an unwrapped response of that wrapper class.
class ApiResult<T: Any>: SimpleApiResult<T> {
...
}
@GET("/search/users")
@WrappedResponse(ApiResult::class)
fun getUsers(@Query("q") query: String): Single<List<User>>githubApi.foo()
.then { foo -> githubApi.bar(foo.name) }
.observe(...)githubApi.foo()
.then { foo -> githubApi.bar(foo.name) }
.thenAll( bar ->
githubApi.baz(bar.name),
githubApi.qux(bar.name)
)
.observe(...)SimpleApiClient.all(
githubApi.foo(),
githubApi.bar()
).observe(...)SimpleApiClient.all(
githubApi.foo(),
githubApi.bar()
).then { array -> // the return type is Array<Any>, you should cast them, e.g. val users = array[0] as List<User>
githubApi.baz()
}.observe(...)githubApi.getUsers("google")
.retryInterval(maxRetryCount = 3, delaySeconds = 5) // retry up to 3 times, each time delays 5 seconds
.retryExponential(maxRetryCount = 3, delaySeconds = 5) // retry up to 3 times, each time delays 5^n seconds, where n = {1,2,3}
.observe(...)The api call will be cancelled automatically in corresponding lifecycle callback. For instance, an api call is made in onStart(), it be will cancelled automatically in onStop.
githubApi.getUsers("google")
.autoDispose(this)
.observe(...)val call = githubApi.getUsers("google").observe(...)
call.dispose()To enable response mocking, set SimpleApiClient.Config.isMockResponseEnabled to true.
To make the api return a successful response with provided json
@GET("/repos/{user}/{repo}")
@MockResponse(R.raw.get_repo)
fun getRepo(@Path("user") user: String, @Path("repo") repo: String): Single<Repo>To make the api return a client side error with provided json
@GET("/repos/{user}/{repo}")
@MockResponse(json = R.raw.get_repo_error, status = Status.CLIENT_ERROR)
fun getRepo(@Path("user") user: String, @Path("repo") repo: String): Single<Repo>json parameter of MockResponse is optional, you can set the status only, then you receive empty string.
Possible Status values:
enum class Status {
SUCCESS, AUTHENTICATION_ERROR, CLIENT_ERROR, SERVER_ERROR, NETWORK_ERROR, SSL_ERROR
}To mock a response with success status only, you should return Completable.
@DELETE("/repo/{id}}")
@MockResponse(status = Status.SUCCESS)
fun deleteRepo(@Path("id") id: String): CompletableCopyright 2017 Jay Chang
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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent