OpenPNE API 仕様

最終更新日:2006/09/03

目次


1. OpenPNE API とは?

OpenPNE APIとは、
SNSサーバ上にある認証情報およびSNSのデータを、外部サーバに対してHTTP通信により提供するためのAPIである。
認証情報とは、
SNSサーバでユーザが認証済みである事を示す情報である。
SNSのデータとは、
OpenPNE SNS側のサーバのデータベースに保存されているデータを指す。 例えば、「ニックネーム」「プロフィール写真のURL」「フレンドリスト」などである。
外部サーバとは、
SNSサーバから認証情報SNSのデータを取得し、SNSとは独立したサービスを提供するサーバである。

2. 概要

2.1. 通信主体

SNSサーバ(APIサーバ) ⇔ 外部サーバ(APIクライアント) 間のサーバ間通信

2.2. プロトコル

XML-RPCの仕様に準拠。文字コード系はUTF-8とする。

2.3. セキュリティ

SNSサーバ、外部サーバ間のAPI通信に対しては、SNSサーバ側(OpenPNEアプリケーション)でIP制限を行う


3. 認証情報の受け渡し

3.1. 概要

  1. SNSサーバ側で認証済みのユーザに対して、以下の値を埋め込んだ外部サーバへのリンクを生成する
    • セッションID(後述)
    • メンバーID
    • リンク生成日時(YYYYMMDDHHMMSS形式)
  2. 外部サーバ側は、受け取ったリクエストをSNSサーバへAPI通信で送る (リンク生成日時が古いものは外部サーバ側で弾いてもよい)
  3. SNSサーバ側は、外部サーバから受け取ったリクエストを検証し結果を返す

3.2. セッションIDの生成方法

  • APIトークン(SNS側の設定ファイで設定した文字列)
  • メンバーID
  • メンバートークン(後述)
  • リンク生成日時(YYYYMMDDHHMMSS形式)
を文字列連結したものをmd5でハッシュ化する。
$session_id = md5($api_token . $c_member_id . $c_member_token . $datetime);

3.3. メンバートークン

メンバーに紐付く値で、SNSサーバが保持する。

値はメンバーがSNSにログインする毎に変更する。

3.4. 外部サーバへのURL

URL例
http://app.example.net/entry?sid=b51a44e6a82cc0d6be9ecadea513c618&mid=237&dt=20060326032450

3.5. 認証API通信

URIhttp://sns.example.com/?m=api&a=do_xmlrpc
encodingUTF-8
methodName000_auth
parameters
要素名説明
sidstringセッションID
midintメンバーID
dtstringリンク生成日時(YYYYMMDDHHMMSS形式)

リクエスト例

POST URI
http://sns.example.com/?m=api&a=do_xmlrpc
<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
<methodName>000_auth</methodName>
<params>
<param>

<value><struct>
<member><name>sid</name>
<value><string>b51a44e6a82cc0d6be9ecadea513c618</string></value>
</member>
<member><name>mid</name>

<value><int>237</int></value>
</member>
<member><name>dt</name>
<value><string>20060326032450</string></value>

</member>
</struct></value>
</param>
</params>
</methodCall>

PHPコード例

<?php
require_once "XML/RPC.php";
...
$params = array(
    "sid" => strval($sid),
    "mid" => intval($mid),
    "dt"  => strval($dt),
);
$params = array(XML_RPC_encode($params));
$msg = new XML_RPC_Message("000_auth", $params);

$cli = new XML_RPC_Client("/?m=api&a=do_xmlrpc", "sns.example.com");
$cli->send($msg);
...
?>

レスポンス例(成功)

メンバーIDを返す。

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
  <params>

    <param>
     <value><int>237</int></value>
    </param>
  </params>
</methodResponse>

レスポンス例(失敗)(ユーザが正常登録状態にない場合)

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
<fault>
  <value>

    <struct>
      <member>
        <name>faultCode</name>
        <value><int>51</int></value>

      </member>
      <member>
        <name>faultString</name>
        <value><string></string></value>

      </member>
    </struct>
  </value>
</fault>
</methodResponse>

4. データ取得

4.1. メソッド名

methodName説明
001_get_c_memberメンバー情報取得
......

4.2. データ取得例

4.2.1. メンバー情報取得

リクエスト
URIhttp://sns.example.com/?m=api&a=do_xmlrpc
encodingUTF-8
methodName001_get_c_member
parameters
要素名説明
target_c_member_idint取得対象のメンバーID
my_c_member_idint自分のメンバーID
リクエスト例

3番のメンバーが10番のメンバーを見た場合

<?xml version="1.0" encoding="UTF-8"?>

<methodCall>
<methodName>001_get_c_member</methodName>
<params>
<param>
<value><struct>
<member><name>target_c_member_id</name>

<value><int>10</int></value>
</member>
<member><name>my_c_member_id</name>
<value><int>3</int></value>

</member>
</struct></value>
</param>
</params>
</methodCall>

PHPコード例

<?php
require_once "XML/RPC.php";
...
$params = array(
	"target_c_member_id" => intval($target_c_member_id),
	"my_c_member_id"     => intval($my_c_member_id),
);
$params = array(XML_RPC_encode($params));
$msg = new XML_RPC_Message("001_get_c_member", $params);

$cli = new XML_RPC_Client("/?m=api&a=do_xmlrpc", "sns.example.com");
$cli->send($msg);
...
?>
レスポンス
要素名説明
c_member_idintメンバーID
nicknamestringニックネーム
image_urlstring画像URL(SNSサーバ上の画像の絶対パス)
birth_yearint誕生年(公開設定による)
birth_monthint誕生月
birth_dayint誕生日
access_datestring(date)最終ログイン日時
r_datestring(date)SNS登録日時
profile---以下プロフィール項目(SNS設定により可変)
sexstring性別
blood_typestring血液型
pre_addr_prefstring現住所(都道府県)
old_addr_prefstring出身地(都道府県)
self_introstring自己紹介

date: YYYYMMDDHHMMSS

レスポンス例
<?xml version="1.0" encoding="UTF-8"?>

<methodResponse>
<params>
<param>
  <value>
    <struct>
      <member>
        <name>c_member_id</name>

        <value><int>10</int></value>
      </member>
      <member>
        <name>nickname</name>

        <value><string>ハチス</string></value>
      </member>
      <member>
        <name>image_url</name>

        <value>
          <string>http://sns.example.com/img.php?filename=m_10_1133710936.jpg</string>
        </value>
      </member>
      <member>

        <name>birth_year</name>
        <value><int>1982</int></value>
      </member>
      <member>

        <name>birth_month</name>
        <value><int>2</int></value>
      </member>
      <member>

        <name>birth_day</name>
        <value><int>15</int></value>
      </member>
      <member>

        <name>access_date</name>
        <value><string>20060116113706</string></value>
      </member>
      <member>

        <name>r_date</name>
        <value><string>20050817000000</string></value>
      </member>
      <member>

        <name>profile</name>
        <value>
          <struct>
            <member>
              <name>sex</name>

              <value><string>男性</string></value>
            </member>
            <member>
              <name>blood_type</name>

              <value><string>o</string></value>
            </member>
            <member>
              <name>pre_addr_pref</name>

              <value><string>東京都</string></value>
            </member>
            <member>
              <name>old_addr_pref</name>

              <value><string>埼玉県</string></value>
            </member>
            <member>
              <name>self_intro</name>

              <value><string>演劇サークルに入りました。12/14-18に初舞台です。
毎日稽古で忙しいです。合間をぬって出社します。</string></value>
            </member>
          </struct>
        </value>
      </member>

    </struct>
  </value>
</param>
</params>
</methodResponse>

5. ポイント

5.1. ポイント加算(減算)通信

リクエスト

URIhttp://sns.example.com/?m=api&a=do_xmlrpc
encodingUTF-8
methodName101_add_point
parameters
要素名説明
c_member_id *intポイント操作対象のc_member_id
point *intポイント増分(負の数の場合は減算)
tagsarrayタグ情報(複数指定可能)
memostringメモ
* : 必須項目

レスポンス

  • 成功した場合、総ポイント残高を返す。
  • 失敗した場合、エラーコードとエラーメッセージを返す。

5.2. ポイント残高照会通信

リクエスト

URIhttp://sns.example.com/?m=api&a=do_xmlrpc
encodingUTF-8
methodName002_get_member_point
parameters
要素名説明
c_member_id *intポイント照会対象のc_member_id
* : 必須項目

レスポンス

  • 成功した場合、総ポイント残高を返す。
  • 失敗した場合、エラーコードとエラーメッセージを返す。

6. エラーの場合

6.1. エラーコード一覧

種別 faultCodefaultString意味
XML-RPC 1Unknown methodサーバが関知しないメソッドの実行を要求された際に返されます。
2Invalid return payloadこのエラーは、実際のところサーバやコードではなくクライアント側で 発生します。しかし、これはサーバが自分で理解できない何かを返したことを 示します。
3Incorrect parametersサーバがメソッドに対応したシグネチャを保持しており、クライアントから 渡されたパラメータがいずれのシグネチャにも一致しなかった際に発生します。
4Can't introspect: method unknownこのエラーは、組み込みの system.*() メソッドから 発生するもので、サーバ上で未定義のメソッドを実行しようとした際に起こります。
5Didn't receive 200 OK from remote serverこのエラーは、サーバからの応答として HTTP/1.1 200 OK が戻ってこなかった際に クライアント側で発生します。エラーの詳細な情報は、上のメッセージの最後に 付け加えられます。
6The requested method didn't return an XML_RPC_Response object. 
7Invalid request payload 
OpenPNE 51''ユーザが正常登録状態にない
52''ユーザが特定できない
53''データベースに接続できない
54''リクエストコマンドコードが不正
55''リクエストパラメータに不足がある
56''データベースに存在しないデータを取得しようとしている
57''データの取得権限がない
58''サーバ側不特定エラー、もしくはメンテナンス中
59''クライアント側不特定エラー
XML 100?XML_ERROR_NONE
101?XML_ERROR_NO_MEMORY
102?XML_ERROR_SYNTAX
103?XML_ERROR_NO_ELEMENTS
104?XML_ERROR_INVALID_TOKEN
105?XML_ERROR_UNCLOSED_TOKEN
106?XML_ERROR_PARTIAL_CHAR
107?XML_ERROR_TAG_MISMATCH
108?XML_ERROR_DUPLICATE_ATTRIBUTE
109?XML_ERROR_JUNK_AFTER_DOC_ELEMENT
110?XML_ERROR_PARAM_ENTITY_REF
111?XML_ERROR_UNDEFINED_ENTITY
112?XML_ERROR_RECURSIVE_ENTITY_REF
113?XML_ERROR_ASYNC_ENTITY
114?XML_ERROR_BAD_CHAR_REF
115?XML_ERROR_BINARY_ENTITY_REF
116?XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF
117?XML_ERROR_MISPLACED_XML_PI
118?XML_ERROR_UNKNOWN_ENCODING
119?XML_ERROR_INCORRECT_ENCODING
120?XML_ERROR_UNCLOSED_CDATA_SECTION
121?XML_ERROR_EXTERNAL_ENTITY_HANDLING

6.2. レスポンス例

リクエストパラメータに不足がある場合

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
<fault>
  <value>
    <struct>

      <member>
        <name>faultCode</name>
        <value><int>3</int></value>
      </member>

      <member>
        <name>faultString</name>
        <value><string>Incorrect parameters passed to method: Signature permits 1 parameters but the request had 0</string></value>
      </member>

    </struct>
  </value>
</fault>
</methodResponse>

7. 参考URL