Marvelous 0.7.3

Marvelous 0.7.3

TestsTested
LangLanguage Obj-CObjective C
License MIT
ReleasedLast Release Dec 2014

Maintained by Unclaimed.


Downloads

Total113
Week0
Month3

Installs

Apps42
powered by Segment

GitHub

Stars39
Watchers5
Forks3
Issues0
Contributors0
Pull Requests2

Code

Files90
LOCLines of Code 3,015


Marvelous 0.7.3

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.

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