FourMarks for Delicious.com

FourMarks is an Objective-C client library for the Delicious bookmarking service.

1. Features

• Full implementation of the v1 API
• Request throttling with AHDispatch - (defaults to 1 second)
• XCText unit test suite.
• CocoaPods integration.
• API Reference Documentation with a build to install the docset in Xcode.
• Built on top of AFNetworking 2.0.

2. FourMarks API

The FourMarks API allows programmatic access to the following Delicious entities (no pun intended):

• Posts
• Tags
• Bundles

Full API Reference Documentation is also available.

3. Requirements

FourMarks is written for ARC-enabled apps. By default your build target will need to comply with one of the following:

• iOS 6.0 or greater
• Xcode 5.0 or greater

If you aren't using ARC, you can still use FourMarks by specifying the -fobjc-arc compiler flag for the implementation files (*.m) in your target's Compile Sources section of the Build Phases tab.

FourMarks depends on the CocoaPods system and the following projects via CocoaPods:

• AFNetworking 2.0
• AHDispatch
• TBXML
• ISO8601DateFormatter

4. Installation

FourMarks depends on CocoaPods in order to build successfully. Installation via CocoaPods is the only recommended way of integrating FourMarks with your project.

4.1 CocoaPods

Simply add the following line to your project's Podfile:

pod 'FourMarks'

then, at the command line, from the same directory as your Podfile, run

pod install

Bear in mind that you will not get the unit test suite or the ability to install the AppleDoc docset locally if simply integrating FourMarks with your project as explained above.

4.2 Unit Tests & the Docset

If you would like to install the included AppleDocs docset locally so the docset appears in the Xcode Documentation Viewer, or view and run the XCTest unit test suite you will need to clone the repo from GitHub to your local machine. You will need to run the CocoaPods command pod install in the root directory of the repo before building the "Install AppleDocs" target for the project. By default, the docset is installed to the "~/Library/Developer/Shared/Documentation/DocSets" location with the package name of "com.alienhitcher.FourMarks.docset".

5. Configuration

Because the Delicious API doesn't require a Developer Account, Token or Key, FourMarks can be used without any configuration at all. Getting started coding with FourMarks as simple as what you see in the Coding Quick Start example.

That said, it is possible to override the default API Endpoint by including keys in your app's Info.plist file. The following key combinations are available listed in order of priority:

• delicious.api.host - for example: "https://api.delicious.com"
• delicious.api.path - for example: "v1"

or:

• delicious.api.url - for example: "https://api.delicious.com/v1/"

5.1 NSUserDefaults

It is possible to retrieve the user's account name and password from NSUserDefaults with FourMarks. For this mechanism to work successfully, ensure that you use the following keys when storing the user's authentication credentials in NSUserDefaults:

• delicious.account.username
• delicious.account.password

These settings can then be used by intializing an FMAccount object with the following code:

FMAccount *account = [FMAccount defaultAccount];

6. Coding Quick Start

After installation, import the library header file somewhere sensible in your code:

#import "FourMarks.h"

then create an instance of FMSession initialized with the credentials of a valid Delicious account:

FMSession *session = [[FMSession alloc] initWithUsername:@"foo" password:@"bar"];

[session addPost:[NSURL URLWithString:@"http://www.google.com"]
           title:@"My Google URL quick post from FourMarks"
            tags:@[@"ah-search", @"ah-engine"]
          result:^(FMResult *result) { 

               //do something with the result
               NSLog(@"result message:%@, code: %@", [result message], [result code]);                        
          }
         failure:^(NSError *error) {
             // react to the network error
         }
];

7. Unit Tests

FourMarks includes a suite of unit tests within the FourMarksTests subdirectory. Tests have been implimented using the XCTest framework. Tests run off data in the supporting file "FourMarksTestData.plist" There are 2 types of unit tests included with the code:

1. Lifecycle Test Suites. Useful for testing major parts of the library. Tests a number of API calls that simulate typical use cases, such as creating updating and deleting posts, creating & deleting bundles, renaming tags, etc…

2. Single API Call Tests for each individual API call. Useful if you make changes to part of this library and want to test your changes without running the test suite to test the entire library against the live Delicious API.

Cloning the repo from GitHub will give you access to the XCTest unit tests. They live in the FourMarksTests folder, and are a good place to find working examples of using FourMarks.

7.1 Configure

As with using FourMarks directly, the included unit tests require no configuration before use. Parameter values for the API calls made in the unit tests however, can be modified, and are stored in the supporting file named FourMarksTestData.plist.

7.2 Build

You will need to run the CocoaPods command pod install in the root directory of the repo before building for testing with ⇧⌘U.

8. Reference Documentation

• FourMarks API Reference Documentation
• The official Delicious API v1 documentation is available via AVOS Systems, Inc. on GitHub.

9 Contact

FourMarks is maintained by Ray Scott (@rayascott).

10 License

FourMarks is available under the MIT license. For more information, see the included LICENSE file.