Marvelous

An unofficial native interface to the Marvel Comics API for both iOS and OSX platforms.

Showing:

Popularity

Downloads/wk

0

GitHub Stars

38

Maintenance

Last Commit

7yrs ago

Contributors

1

Package

Dependencies

0

License

MIT

Categories

Readme

Marvelous

Marvelous is an unofficial native interface to the Marvel Comics API for both iOS and OSX platforms. It is built on top of the Foundation framework and it uses the high-level operation and networking abstractions built into the Cocoa framework. The design of this interface aims to be easy-to-use in your projects and semantically related to the API.

Requirements

Marvelous requires:

  • XCode 5.0 or higher
  • iOS 7.0 (and higher) or OSX 10.8 Mountain Lion (and higher)
  • ARC

How To Get Started

Marvelous can be included into your projects by downloading a compiled library or framework that you will setup by hand with lots of wisdom and patience or you can just use Cocoapods the library as a pod.

Installing by getting your hands dirty

  1. Download the static library for iOS or the framework for OSX.
  2. Install the static library or framework into your prject.
  3. Create your Marvel developer account to obtain the public and private keys required to sign any request to the API. Of course, you can skip this step in case you already have a developer account.
  4. Play with it 'til you drop!
  5. Check the documentation included with the library/framework .zip files for further information about the library.
  6. Check the Marvel Comics online documentation for further information about the API calls.

Installing using CocoaPods

  1. Install Cocoapods on your system. If you already have it installed, proceed to the next step.
$ sudo gem install cocoapods
  1. Create a Podfile which will define the dependencies of your project.
YourProject$ pod init
  1. Add the Marvelous dependency into your Podfile.
platform :ios, '7.0'
# platform :osx, '10.8'
xcodeproj 'YourProject'
pod 'Marvelous' #, '~> 0.7.3'
# ... more settings ...
  1. Install the dependencies.
YourProject$ pod install
  1. Open the YourProject.xcworkspace and build in case you've created a new XCode project with Cocoapods. Otherwise, you should integrate your workspace into the Podfile.
workspace 'YourProject'

Architecture

API Interface

The manager (or singleton) class that provides the interface to the API and it is able to call a certain API and return its response as a callback.

  • RCMarvelAPI

Filters you might use

Depending the call, you are able to use filters to finegrain your search. You just need to pass 'em as a parameter to the method you call on the RCMarvelAPI class.

  • RCCharacterFilter
  • RCComicsFilter
  • RCCreatorFilter
  • RCEventFilter
  • RCSeriesFilter
  • RCStoriesFilter

Objects you might receive

Every time the RCMarvelAPI class receives a non-error response from the API, it will return a RCQueryInfoObject object and a RCCharacterObject, RCComicsObject, RCCreatorObject, RCEventObject, RCSeriesObject or a RCStoryObject object. These objects can also contain other custom objects.

  • RCQueryInfoObject
  • RCCharacterObject
  • RCComicsObject
  • RCCreatorObject
  • RCEventObject
  • RCSeriesObject
  • RCStoryObject
  • RCListObject
  • RCImageObject
  • RCComicPriceObject
  • RCComicDateObject
  • RCTextObject
  • RCSummaryObject
  • RCURLObject

Enumerations you might encounter

Both the filters and the objects provide enumerations to avoid any ambiguity and make your life easier.

  • RCAPITypes
  • RCOrderByTypeCodes
  • RCIssueFormatCodes
  • RCIssueTypeCodes
  • RCFrequencyTypeCodes
  • RCDateDescriptorCodes
  • RCImageAspectRatioCodes
  • RCImageSizeCodes
  • RCBooleanValueCodes

Example Usage

#import <Marvelous/RCMarvelAPI.h>

// First, you need to define your Marvel developer public and private keys
[RCMarvelAPI api].publicKey = @"YourMarvelPublicKey";
[RCMarvelAPI api].privateKey = @"YourMarvelPrivateKey";

// Then, you can use the API interface to search for a single resource by its identifier
NSNumber *identifier = @1234;

[[RCMarvelAPI api] characterByIdentifier:identifier andCallbackBlock:^(id result, RCQueryInfoObject *info, NSError *error) {
  NSLog(@"ERROR: %@", error);
  NSLog(@"QUERY INFO: %@", info);
  NSLog(@"RESULT: %@", result);
}];

// Or you can use the API interface to search for multiple resources by its filter
RCCharacterFilter * filter = [[RCCharacterFilter alloc] init];

filter.nameStartsWith = @"Wol";
filter.limit = @2;
filter.orderBy = @[@(RCOrderByTypeCodeNameAscending)];

[[RCMarvelAPI api] charactersByFilter:filter andCallbackBlock:^(NSArray *results, RCQueryInfoObject *info, NSError *error) {
  NSLog(@"ERROR: %@", error);
  NSLog(@"QUERY INFO: %@", info);
  NSLog(@"RESULTS: %@", results);
}];

// Finally, you can use the API interface to search for multiple resources by an identifier and a filter
NSNumber identifier = @4321;
RCCharacterFilter * filter = [[RCCharacterFilter alloc] init];

filter.name = @"Captain America";
filter.orderBy = @[@(RCOrderByTypeCodeDateModifieDescending)];

[[RCMarvelAPI api] charactersByComicIdentifier:identifier filter:filter andCallbackBlock:^(NSArray *results, RCQueryInfoObject *info, NSError *error) {
  NSLog(@"ERROR: %@", error);
  NSLog(@"QUERY INFO: %@", info);
  NSLog(@"RESULTS: %@", results);
}];

Unit Tests

Marvelous includes a suite of unit tests within the MarvelousTests folder. You can execute the test suite inside XCode by selecting either the Marvelous or the MarvelousOSX scheme and then pressing the ⌘+U key shortcut.

Documentation

Marvelous includes documentation written in HeaderDoc, which is included with XCode. It also support the new feature introduced by XCode 5.0 to display source code comments as documentation in the Quick Help Inspector, in the Help Popup and Code Completion.

Online Documentation

Marvelous online documentation is available on CocoaDocs. You're also able to import these docs as docsets to XCode and/or to Dash.

TODOs

  • RCMarvelAPI asynchronous tests

Credits

Marvelous was created by Javier Cicchelli as a side project while working on some other stuff. I'm a big Marvel fan (Practically I've been raised on X-Men so go figure...) and I've got so inspired by such a simple and nice API design described on Marvel's Interactive documentation that well... I dedicated some time into crafting this beauty you're about to use.

The truth is that working on this library helped me clean my head and keep my sanity! :P

Contact

Stay tune for more updates regarding this nice library, among other awesome stuff! Also don't hesitate to reach me for comments, suggestions, issues and constructive criticism.

Maintainers

Just one more thing, folks...

Marvelous was crafted with Objective-C, some Software engineering and lots of geekness, fandom and love. And you're all welcome to contribute to it in any way possible: from reporting issues or fixing bugs to share its existence on Twitter/Facebook/etc.. or just use it on your apps. Just don't forget to mention it and spread the love around, will ya?

If any of you guys who are working on Marvel read these parragraphs, I've just want you to use this library on your apps! That would be like a dream come true and I'll be tremendously happy for giving you guys something back for sticking up with me since I remember. In a way, this is my little thank you to you, Marvel. ;)

License

Marvelous is available under the MIT license. See the LICENSE file for more info.

Attribution

API data provided by Marvel. © 2014 Marvel

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100