MarvelAndroid

I’m happy to say that Beta 1 of MarvelAndroid is available!

What is it for?

This library is aimed at making it easier for developers to make awesome comic book apps with the Marvel Comics Api. There is a wealth of awesome Marvel content available through the api, and with MarvelAndroid quickly accessing that content is now easier than ever.

What can it do?

MarvelAndroid supports retrieving content for each of the 6 core entity types the API makes available:

– Characters
– Comics
– Events
– Series
– Stories
– Creators

This content can be queried in a number of ways. You can perform a general search to return all comics, all series, etc. Or, you could search for all comics associated with a specific event or maybe search for all characters whose name starts with “spider”.

See the Interactive Documentation for a full list of ways in which content can be queried.

Initialization

To use this library, you must first initialize it within your code using your own public and private keys acquired from the [Marvel Developer Portal](http://developer.marvel.com/).

 MarvelAndroid.initialize(context, "your private key", "your public key", cacheSize);  

Searching

Lets take a look at an example of searching for a content. In this case we want to retrieve all characters whose name starts with “spider”.

First, create a `CharacterQueryParams` object to define the characters query.

 CharacterQueryParams queryParams = new CharacterQueryParams();  
 queryParams.setNameStartsWith("spider");  

Next, get an instance of `CharacterEndpoint`.

 MarvelAndroid marvelAndroid = MarvelAndroid.getInstance();  
 CharacterEndpoint characterEndpoint = marvelAndroid.getCharacterEndpoint();  

Through the endpoint, characters can be return through a number of methods such as `getCharacter()` and `getCharactersForComicId()`. Each method has two forms as well. One that takes a callback, and another that returns an RxJava Observable.

 characterEndpoint.getCharacters(queryParams, new Callback<RequestResponse<Character>>() {  
   @Override  
   public void success(RequestResponse<Character> characterRequestResponse, Response response) {  
   }  
   @Override  
   public void failure(RetrofitError error) {  
   }  
 });  
 Observable<RequestResponse<Character>> characters = characterEndpoint.getCharacters(queryParams);  

Handling results

With the returned response, a list of characters matching the specified query can be accessed. The results are returned in pages, with a default page size of 20. The page size and current page offset can be set through the `CharacterQueryParams`.

 characterEndpoint.getCharacters(queryParams, new Callback<RequestResponse<Character>>() {  
   @Override  
   public void success(RequestResponse<Character> characterRequestResponse, Response response) {  
     List<Character> characters = characterRequestResponse.data.results;  
     for (Character character : characters) {  
       print("Name: " + character.name + " Id: " + character.id + " Description: " + character.description);  
     }  
   }  
   @Override  
   public void failure(RetrofitError error) {  
   }  
 });  

Lets add another endpoint

In the previous example, we retrieved a list of characters. Now, lets look at how you could retrieve a list of comics for a returned character.

 ComicQueryParams queryParams = new ComicQueryParams();  
 queryParams.setOrderBy(ComicQueryParams.OrderBy.Title);  
 for (Character character : characters) {  
  marvelAndroid.getComicEndpoint().getComicsForCharacterId(character.id, queryParams, new Callback<RequestResponse<Comic>>() {  
    @Override  
    public void success(RequestResponse<Comic> requestResponse, Response response) {  
     List<Comic> comics = requestResponse.data.results;  
     for (Comic comic : comics) {  
       print("Title: " + comic.title + " Description: " + comic.description);  
     }  
    }  
    @Override  
    public void failure(RetrofitError error) {  
    }  
  });  
 }  

Images

One of the best parts about comics, and Marvel’s API is all the incredible artwork that is available. For any entity, you can retrieve a partial url path that can be used to build a full url to an image representation of the entity. Each image can be accessed as a variety of variants which are documented here.

 comic.thumbnail.path + "/" + "image variant name" + "." + comic.thumbnail.extension  

http://i.annihil.us/u/prod/marvel/i/mg/2/e0/55d225446d1c0/landscape_medium.jpg

http://i.annihil.us/u/prod/marvel/i/mg/2/e0/55d225446d1c0/portrait_incredible.jpg

Use and Contribute

You can view/download the code at GitHub.

Please give feedback, log any issues you find, or create enhancement requests.

Leave a Reply