[XCODE] Zaim APIをiOSから利用する方法

こんにちは、@yoheiMuneです。
先日、「EasyPost to Zaim」というiOSアプリをリリースさせて頂き、多くの皆様に利用頂いており本当にありがとうございます！
本日は「EasyPost to Zaim」で利用しているZaim APIについて、iOSから利用する方法を記載したいと思います。

Zaimとは、Zaim APIとは

Zaimとはオンライン家計簿ツールで、iOS、Android、Webから利用することが出来ます。（最近Web版もリリースされました）。
オンラインに情報があるので、今までのようにいつでも利用でき、自分の状況に合わせてPCやスマホからデータを入力・参照できて便利な家計簿です。

そしてそのZaimを外部から利用するためのAPIが用意されています。開発者の閑歳さんには大感謝です。 本記事では、公開されたZaimのAPIをiOSから利用する方法を記載したいと思います。

ZaimAPIを利用するためのアプリケーション登録を行う

ZaimAPIを利用するためには、他のサービスと同様に、アプリケーション登録を行う必要があります。
以下のリンクより、アプリケーションの登録を行うことが出来ます。

- https://dev.zaim.net

上記のページからログインして、「新しいアプリケーションの登録」を行います。
そこで登録した際に発行される、ComsumerKeyやComsumerSecretなどの値をアプリケーションから利用します。

* 自分が登録した時点では、サービス種を「ブラウザアプリ」にしないと後述の認証実装がうまく行きませんでした。クライアントアプリにするとたぶんダイジェスト認証などが入って、後述のOAuth用ライブラリが対応していないのかなぁ。。

iOSでOAuthを行う

それではここからがiOSでの具体的な実装内容です。
ZaimAPIは、認証にOAuth1.0aを利用しています。そのためZaimAPIでクライアント情報を取得するためには、事前に認証を行う必要があります。
iOSでOAuthを行うためにはいくつかの方法がありますが、今回はGTMOAuthというライブラリを利用します。
具体的なライブラリの使い方は、以下のブログ記事で記載しておりますので、そちらをご参照頂けると幸いです。

[XCODE] iOSアプリでOAuth認証を行う、はてブAPIを利用する

上記のブログ内で作成した以下のインスタンスを、後続の実装で利用します。

GTMOAuthAuthentication *mAuth

Zaim APIを利用する

ではここからが本番で、ZaimAPIを利用します。今回利用するZaimAPIは、既に公開済みのver1のAPIです。
APIの詳細はこちらから利用することが出来ます。

カテゴリ一覧、ジャンル一覧を取得する

Zaimで出費状況を登録するために入力するカテゴリやジャンルを取得します（ver1では、個人でカスタマイズしたカテゴリ/ジャンルの取得は出来ず、Zaimで最初から定義されたカテゴリやジャンルを取得できます）。

Zaimで定義したカテゴリとジャンルは、OAuth認証なしで取得することが出来ます。
実装内容は以下のような感じになります。
（カテゴリを取得する）

// URLとHTTPメソッドを指定します。
NSURL *url = [NSURL URLWithString:@"https://api.zaim.net/v1/category/pay.json"];
NSMutableURLRequest *request = [[NSMutableURLRequest alloc] initWithURL:url];
request.HTTPMethod = @"POST";

// 日本語のカテゴリを取得したい場合には、パラメータを設定します。
if ([self ifYouWantJapanese]) {
    NSString *param = @"lang=ja";
    request.HTTPBody = [param dataUsingEncoding:NSUTF8StringEncoding];
}

// 非同期リクエストを送信する。
// 送信終了時には、引数に指定したコールバックハンドラーが実行される。
[NSURLConnection
	sendAsynchronousRequest:request 
	queue:[[NSOperationQueue alloc] init] 
	completionHandler:^(NSURLResponse *response, NSData *data, NSError *error) {
    
    // カテゴリはJSON形式で取得できます。
    NSString *json = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
    
    // JSONをNSDictionaryに変換します。
    NSDictionary *jsonDict = [NSJSONSerialization JSONObjectWithData:data options:NSJSONReadingMutableContainers error:&error];    
}];

ジャンルを取得したい場合には、送信するURLを変更するだけでジャンル一覧を取得できます。

送信先URL：https://api.zaim.net/v1/genre/pay.json

これで出費登録に利用するカテゴリとジャンルを取得することが出来ました。

出費登録を行う

続いてZaimAPIを利用して出費登録を行います。出費登録に利用するURLは以下です。

出費登録用URL：https://api.zaim.net/v1/pay/create.json

このURLにはOAuth認証で得た認証情報を利用する必要があります。また具体的な出費内容はパラメータとして指定します。
具体的な実装内容は以下となります。

// 送信先URL、メソッド、コンテンツタイプを指定します。
NSURL *url = [NSURL URLWithString:@"https://api.zaim.net/v1/pay/create.json"];
NSMutableURLRequest *request = [[NSMutableURLRequest alloc] initWithURL:url];
[request setValue:@"application/x-www-form-urlencoded" forHTTPHeaderField:@"Content-Type"];
request.HTTPMethod = @"POST";

// 送信内容を作成し、リクエストに設定します。
NSString *cateogryId = @"101";
NSString *genreId = @"10101";
NSString *amount = @"1000";
NSString *date = @"2013-5-10";
NSString *comment = @"Some Comment";
NSString *bodyString = [NSString stringWithFormat:@"category_id=%d&genre_id=%d&amount=%@&date=%@&comment=%@", categoryId, genreId, amountString, dateString, comment];
request.HTTPBody = bodyString;

// 認証情報を付与します。
// HTTPBodyなども全部付与して、リクエスト送信直前に認証情報を付与します。
// そうしないと改ざん防止のダイジェストが送信元と送信先でずれます。
[mAuth authorizeRequest:request];

// リクエストを送信します。
[NSURLConnection
	sendAsynchronousRequest:request 
	queue:[[NSOperationQueue alloc] init] 
	completionHandler:^(NSURLResponse *response, NSData *data, NSError *error) {

    // エラーチェックをします。
    int statusCode = ((NSHTTPURLResponse *)response).statusCode;
    if (statusCode == 400 || statusCode == 401 || statusCode == 403) {
        // 認証エラー
    } else if (error || (statusCode != 200 && statusCode != 201)) {
        // 何らかのエラー（圏外、タイムアウトなど）
    } else {        
        // 処理成功
    }    
}];

こんな感じで出費登録を行うことができます。 他のサービスのAPIと同様に認証さえ実装できてしまえば、あとは簡単に使うことができます。

最後に

今回のブログでは、「EasyPost to Zaim」で利用しているZaimのAPIを中心に、ZaimAPIをiOSから使う方法を記載しました。
上記で紹介したAPI以外にも色々とAPIがありますので、https://dev.zaim.netから調べてみてください。

EasyPost to Zaimは、より進化したAPIも利用しつつ、更に便利なアプリケーションに成長していきたいと思います。
最後までご覧頂きましてありがとうございました。