ここの情報は古いです。ご理解頂いた上でお取り扱いください。

Changeset 12882


Ignore:
Timestamp:
Sep 14, 2009, 11:33:37 PM (13 years ago)
Author:
ebihara
Message:

added a description about GData and AtomPub? with more supplementations

Location:
OpenPNE3/doc/branches/develop/OpenPNEWebAPI
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • OpenPNE3/doc/branches/develop/OpenPNEWebAPI/docs/about.rst

    r12881 r12882  
    55このドキュメントは、OpenPNE Web API を用い、OpenPNE と情報をやり取りするアプリケーションを作成する方を対象にしています。
    66
    7 OpenPNE Web API は Google Data APIs 1.0 (以下 GData) に基づいて実装されています。このドキュメントでは GData の詳細については解説しないので、読み進めるにあたっては GData の仕様について理解している必要があります。
     7OpenPNE Web API は Google Data APIs 1.0 (以下 GData) や RFC 5023 で規定された Atom Publishing Protocol (以下 AtomPub) をベースに作られています。
    88
    9 GData の詳細な仕様については http://code.google.com/intl/ja/apis/gdata/docs/1.0/reference.html から参照することができます。
     9ただし GData と AtomPub の差異が少なくないことなどを鑑み、このドキュメントにおいては GData もしくは AtomPub と重複する仕様であっても解説していきます。
    1010
     11 * GData の詳細な仕様については http://code.google.com/intl/ja/apis/gdata/docs/1.0/reference.html から参照することができます。
     12 * AtomPub の詳細な仕様については http://tools.ietf.org/rfc/rfc5023.txt から参照することができます。
     13
     14表記について
     15============
     16
     17RFC 2119 で定められたキーワード
     18-------------------------------
     19
     20この文書で扱われる MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, OPTIONAL というキーワードは RFC 2119 に従って解釈される必要があります。
     21
     22例示用の URI
     23------------
     24
     25この文書で例示のために用いられる URI は、 URI Template の書式に従って記述されます。
     26
     27URI Template については http://bitworking.org/projects/URI-Templates/spec/draft-gregorio-uritemplate-03.html を参照してください。
     28
     29解説のための XPath
     30------------------
     31
     32この文書では、例示した XML 文書中の特定要素や属性値などを明確にするために、 XML Path Language 2.0 (以下 XPath) による表記を用います。
     33
     34XPath の構文などについては http://www.w3.org/TR/xpath20/ を参照してください。
     35
     36用語
     37====
     38
     39用語については Atom Publishing Protocol で定められているものに完全に準拠しますが、定義されている用語がすべて本文書で使われているわけではないことに注意してください。
     40

  • OpenPNE3/doc/branches/develop/OpenPNEWebAPI/docs/basic.rst

    r12881 r12882  
    1 ========================
    2 API が提供する機能の概要
    3 ========================
     1====================
     2OpenPNE Web API 概要
     3====================
     4
     5概要
     6====
     7
     8OpenPNE Web API はクライアントがサーバと RFC 4287 で定められた 2 種類の Atom 文書（Atom フィード文書、 Atom エントリ文書）をやり取りしていくことにより、リソースの取得、作成、更新、削除を実現します。
     9
     10OpenPNE Web API で扱えるリソースにはメンバリソースとコレクションリソースが存在します。メンバリソースは個々の操作の対象を表すもので、 Atom エントリ文書によって表現されます。コレクションリソースは複数の操作の対象の集合を表すもので、 Atom フィード文書によって表現されます。
     11
     12メンバリソースとコレクションリソースはそれぞれ対応する URI を持っています。メンバリソースに対応した URI はメンバ URI、コレクションリソースに対応した URI はコレクション URI と呼ばれます。これらの URI に対して適切なリクエストパラメータとリクエストメソッドを用いてアクセスすることにより、リソースに関する操作をおこなうことができます。
     13
     14たとえばコレクション URI に対して GET することで、コレクションリソースを取得できます。そこから特定のメンバリソースのメンバ URI を知り、メンバ URI に対して GET をすることで、メンバリソースを表す Atom エントリ文書を取得できます。取得できた Atom エントリ文書を修正し、修正した文書を取得元のメンバ URI に対して PUT することでメンバリソースを更新できます。取得した Atom エントリ文書を参考にして新しい 文書を作成し、それをコレクション URI に対して POST することで、新しいメンバリソースをコレクションリソースに追加できます。不要になったリソースはメンバ URI に対して DELETE することで削除できます。
     15
     16OpenPNE Web API で利用可能な機能
     17================================
    418
    519各 API では、以下のいずれかもしくはすべての機能が提供されています。
    620
    7 * フィードの取得
    8     * 全文検索
    9     * カテゴリによる絞り込み検索
    10     * 著者や投稿日時などの条件による絞り込み検索
    11     * 取得開始エントリ、取得件数の制限
    12     * 取得結果のソート
    13 * リソースの取得
    14 * リソースの追加
    15 * リソースの更新
    16 * リソースの削除
    17 
    18 各 API を利用するためには、コレクション URI もしくはメンバ URI に対して、適切なリクエストパラメータとリクエストメソッドを用いてアクセスする必要があります。
    19 
    20 ここでの解説用のコレクション URI とメンバ URI は以下になります。
     21 * エントリの一覧の取得
     22     * 全文検索
     23     * カテゴリによる絞り込み検索
     24     * 著者や投稿日時などの条件による絞り込み検索
     25     * 取得開始エントリ、取得件数の制限
     26     * 取得結果のソート
     27 * エントリの取得
     28 * エントリの追加
     29 * エントリの更新
     30 * エントリの削除
     31
     32OpenPNE Web API を使用するための URI
     33====================================
     34
     35OpenPNE Web API は、 OpenPNE3 における api アプリケーションからアクセスできます。
     36
     37api アプリケーションにアクセスするための api.php というフロントコントローラ用スクリプトが存在する場合 (OpenPNE3 のデフォルトの状態)、 URI は以下のような形式になります。
     38
     39通常のコレクション URI:
     40  http://example.com/api.php/feeds/{リソースの種類}
     41
     42親となるリソースが存在する場合のコレクション URI:
     43  http://example.com/api.php/feeds/{リソースの種類}/{親となるリソースの種類}/{親となるリソースの識別子}
     44
     45メンバ URI:
     46  http://example.com/api.php/feeds/{リソースの種類}/{リソースの識別子}
     47
     48また、ここでは、例示用の以下の URI を使って具体的な API の使用方法について解説をおこないます。
    2149
    2250コレクション URI
    23     http://example.com/feeds/example
     51    http://example.com/api.php/feeds/example
    2452
    2553メンバ URI
    26     http://example.com/feeds/example/{id}
    27 
    28 フィードの取得
    29 ==============
    30 フィードはコレクション URI に対して GET することで取得することができます。
     54    http://example.com/api.php/feeds/example/1
     55
     56エントリの一覧の取得
     57====================
     58
     59エントリの一覧はコレクション URI に対して GET することで取得することができます。
    3160
    3261また、適切なリクエストパラメータを付加してアクセスすることで、結果の絞り込みやソートをおこなうことができます。
    … …  
    224253++++++++++++
    225254
    226 start クエリは取得を開始するエントリの番号を指定します。
     255start クエリは取得を開始するエントリの番号を指定します。番号は 1 からはじまります。
    227256
    228257デフォルト値 1 が指定されています。
    … …  
    303332このリクエストでは、発行日時が古い順にエントリを取得できます。
    304333
    305 リソースの取得
     334エントリの取得
    306335==============
    307336
    308 メンバ URI に対して GET することで、リソースを取得できます。
     337メンバ URI に対して GET することで、エントリを取得できます。
    309338
    310339::
    … …  
    338367  </entry>
    339368
    340 リソースの追加
     369エントリの追加
    341370==============
    342371
    343 コレクション URI に対して POST することで、リソースを追加できます。
     372コレクション URI に対して POST することで、エントリを追加できます。
    344373
    345374リクエストの例を以下に示します。
    … …  
    387416  </entry>
    388417
    389 リソースの更新
     418エントリの更新
    390419==============
    391420
    392 メンバ URI に対して PUT することで、リソースを更新できます。
     421メンバ URI に対して PUT することで、エントリを更新できます。
    393422
    394423リクエストの例を以下に示します。
    … …  
    446475  </entry>
    447476
    448 リソースの削除
     477エントリの削除
    449478==============
    450479
    451 メンバ URI に対して DELETE することで、リソースを削除できます。
     480メンバ URI に対して DELETE することで、エントリを削除できます。
    452481
    453482リクエストの例を以下に示します。

  • OpenPNE3/doc/branches/develop/OpenPNEWebAPI/index.rst

    r12881 r12882  
    1212   docs/about
    1313   docs/history
     14   docs/basic
    1415   docs/authentication
    15    docs/basic
    1616
    1717   docs/member_api
Note: See TracChangeset for help on using the changeset viewer.