mirror of
https://github.com/commons-app/apps-android-commons.git
synced 2025-11-04 00:33:55 +01:00
101 lines
3.2 KiB
Markdown
101 lines
3.2 KiB
Markdown
# Wikimedia Android data client
|
|
An Android library for communicating with Wikimedia projects, with Rx bindings and other utilities.
|
|
|
|
## Motivation and philosophy
|
|
|
|
Here are the purposes for creating this library:
|
|
|
|
* Encapsulate the various model structures that are returned by MediaWiki APIs,
|
|
as well as by REST APIs provided by Wikimedia services.
|
|
|
|
* Provide high-level bindings for Retrofit and RxJava for executing calls to MediaWiki APIs to
|
|
further simplify client integration, while also allowing customization and extension.
|
|
|
|
* Provide numerous common utility methods, so that they don't need to be duplicated.
|
|
|
|
## Integration with your app
|
|
|
|
Add the dependency to your Gradle file as usual:
|
|
|
|
```
|
|
implementation "com.dmitrybrant:wikimedia-android-data-client:0.0.18"
|
|
```
|
|
|
|
The only nontrivial point of integration with the library is the `AppAdapter` class: You
|
|
need to create a class that inherits from `AppAdapter` and implement its methods. The
|
|
methods are mostly self-explanatory, and deal with user account management, cookie storage,
|
|
and a few other customizations.
|
|
|
|
Once you create this class (suppose it's called `MyAppAdapter`), you should pass it into
|
|
the `AppAdapter` singleton when your app starts:
|
|
|
|
```
|
|
@Override
|
|
public void onCreate() {
|
|
...
|
|
AppAdapter.set(new MyAppAdapter());
|
|
...
|
|
}
|
|
```
|
|
|
|
## Making calls to APIs
|
|
|
|
Notice that there is an interface called `Service` that contains a number of API definitions
|
|
for talking with a MediaWiki server. To use any of the functions in the interface, you should
|
|
use the `ServiceFactory` class. For example:
|
|
|
|
```
|
|
WikiSite wiki = new WikiSite("en.wikipedia.org");
|
|
|
|
Observable observable = ServiceFactory.get(wiki).fullTextSearch("foo");
|
|
```
|
|
|
|
That's it! Notice that most of the API calls return an `Observable` response which you can
|
|
feed into an Rx subscription.
|
|
|
|
Note: the `ServiceFactory` class contains automatic caching logic, so that multiple calls to
|
|
`get()` the service for the same `WikiSite` will be very efficient.
|
|
|
|
## Custom API calls
|
|
|
|
The `ServiceFactory` class also allows you to provide a service interface with custom
|
|
API functions. Suppose you create your own service interface that looks like this:
|
|
|
|
```
|
|
public interface MyInterface {
|
|
|
|
@GET("action=myawesomeaction")
|
|
Observable<MyAwesomeResponse> myAwesomeApiCall(@Query("parameter1") parameter);
|
|
|
|
}
|
|
```
|
|
|
|
You can then use it with `ServiceFactory` this way:
|
|
|
|
```
|
|
WikiSite wiki = new WikiSite("my.awesome.wiki");
|
|
|
|
Observable observable = ServiceFactory.get(wiki, "https://my.awesome.wiki/", MyInterface.class)
|
|
.myAwesomeApiCall("foo");
|
|
```
|
|
|
|
## Utility methods
|
|
|
|
The library contains a potpourri of utility methods found under the `util` package. Feel free
|
|
to browse through them and use them as necessary.
|
|
|
|
## License
|
|
|
|
Copyright 2019 Wikimedia Foundation
|
|
|
|
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.
|