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

source: OpenPNE3/doc/branches/develop/OpenPNEWebAPI/docs/basic.rst @ 12891

Last change on this file since 12891 was 12891, checked in by ebihara, 10 years ago

added images for explaining

File size: 18.2 KB
Line 
1====================
2OpenPNE Web API 概要
3====================
4
5概要
6====
7
8OpenPNE Web API はクライアントがサーバと RFC 4287 (http://tools.ietf.org/rfc/rfc4287.txt) で定められた 2 種類の Atom 文書(Atom フィード文書、 Atom エントリ文書)をやり取りしていくことにより、リソースの取得、作成、更新、削除を実現します。
9
10OpenPNE Web API で扱えるリソースにはメンバリソースとコレクションリソースが存在します。メンバリソースは個々の操作の対象を表すもので、 Atom エントリ文書によって表現されます。コレクションリソースは複数の操作の対象の集合を表すもので、 Atom フィード文書によって表現されます。
11
12メンバリソースとコレクションリソースはそれぞれ対応する URI を持っています。メンバリソースに対応した URI はメンバ URI、コレクションリソースに対応した URI はコレクション URI と呼ばれます。これらの URI に対して適切なリクエストパラメータとリクエストメソッドを用いてアクセスすることにより、リソースに関する操作をおこなうことができます。
13
14.. image:: image/overview.png
15
16たとえばコレクション URI に対して GET することで、コレクションリソースを取得できます。そこから特定のメンバリソースのメンバ URI を知り、メンバ URI に対して GET をすることで、メンバリソースを表す Atom エントリ文書を取得できます。取得できた Atom エントリ文書を修正し、修正した文書を取得元のメンバ URI に対して PUT することでメンバリソースを更新できます。取得した Atom エントリ文書を参考にして新しい 文書を作成し、それをコレクション URI に対して POST することで、新しいメンバリソースをコレクションリソースに追加できます。不要になったリソースはメンバ URI に対して DELETE することで削除できます。
17
18OpenPNE Web API で利用可能な機能
19================================
20
21各 API では、以下のいずれかもしくはすべての機能が提供されています。
22
23 * エントリの一覧の取得
24     * 全文検索
25     * カテゴリによる絞り込み検索
26     * 著者や投稿日時などの条件による絞り込み検索
27     * 取得開始エントリ、取得件数の制限
28     * 取得結果のソート
29 * エントリの取得
30 * エントリの追加
31 * エントリの更新
32 * エントリの削除
33
34OpenPNE Web API を使用するための URI
35====================================
36
37OpenPNE Web API は、 OpenPNE3 における api アプリケーションからアクセスできます。
38
39api アプリケーションにアクセスするための api.php というフロントコントローラ用スクリプトが存在する場合 (OpenPNE3 のデフォルトの状態)、 URI は以下のような形式になります。
40
41通常のコレクション URI:
42  http://example.com/api.php/feeds/{リソースの種類}
43
44親となるリソースが存在する場合のコレクション URI:
45  http://example.com/api.php/feeds/{リソースの種類}/{親となるリソースの種類}/{親となるリソースの識別子}
46
47メンバ URI:
48  http://example.com/api.php/feeds/{リソースの種類}/{リソースの識別子}
49
50また、ここでは、例示用の以下の URI を使って具体的な API の使用方法について解説をおこないます。
51
52コレクション URI
53    http://example.com/api.php/feeds/example
54
55メンバ URI
56    http://example.com/api.php/feeds/example/1
57
58クライアントから送信する Atom エントリ文書について
59==================================================
60
61そのリソースがどういう Atom エントリ文書によって表現されるかについては、各 API のトップページに解説があります。
62
63(省略可) と記されている要素は、この要素を含めなくても POST や PUT をおこなうことができることを意味しています。また、これらの要素は編集不可でもあり、リクエストされた Atom 文書中にこれらの要素が含まれていたとしても、単に無視されます。
64
65エントリの一覧の取得
66====================
67
68.. image:: image/get_entries.png
69
70エントリの一覧はコレクション URI に対して GET することで取得することができます。
71
72また、適切なリクエストパラメータを付加してアクセスすることで、結果の絞り込みやソートをおこなうことができます。
73
74.. _search-query:
75
76全文検索
77--------
78
79全文検索は、 q クエリを用いることでおこなうことができます。
80
81::
82
83  GET /api.php/feeds/example?q=term HTTP/1.1
84  Host: example.com
85
86検索において英字の大文字と小文字は区別されません。
87
88::
89
90  GET /api.php/feeds/example?q=term1%20term2 HTTP/1.1
91  Host: example.com
92
93%20 は半角スペース文字 ( ) を URL-encode したものです。このリクエストでは、"term1" と "term2" という語を全て含む (AND 検索) エントリを全て取得できます。
94
95::
96
97  GET /api.php/feeds/example?q=%22exact%20phrase%22 HTTP/1.1
98  Host: example.com
99
100%22 は半角二重引用符 (")を URL-encode したものです。このリクエストでは、"exact phrase" というフレーズを含むエントリを全て取得できます。
101
102::
103
104  GET /api.php/feeds/example?q=-term HTTP/1.1
105  Host: example.com
106
107このリクエストでは、"term" という語を含まないエントリを全て取得できます。
108
109これらのクエリは複合できます。
110
111::
112
113  GET /api.php/feeds/example?q=%22exact%20term%22%20term1%20-term2%20term3 HTTP/1.1
114  Host: example.com
115
116このリクエストでは、"exact term" というフレーズを含み、"term1" と "term3" という語を含み、"term2" という語を含まないエントリを全て取得できます。
117
118.. _category-query:
119
120カテゴリ(タグ)による絞り込み検索
121----------------------------------
122
123/-/value 表記
124+++++++++++++
125
126/-/value 形式 (value は任意の文字列) のクエリを指定することで、カテゴリによる検索をおこなうことができます。
127
128::
129
130  GET /api.php/feeds/example/-/baseball HTTP/1.1
131  Host: example.com
132
133このリクエストでは、"baseball" という語に完全一致するカテゴリを持つエントリを全て取得できます。
134
135::
136
137  GET /api.php/feeds/example/-/baseball/japan HTTP/1.1
138  Host: example.com
139
140このリクエストでは、"baseball" と "japan" という語に完全一致するカテゴリを全て持つ (AND 検索) エントリを全て取得できます。
141
142::
143
144  GET /api.php/feeds/example/-/baseball%7Csoccer HTTP/1.1
145  Host: example.com
146
147%7C は半角パイプ文字 (|) を URL-encode したものです。このリクエストでは、"baseball" と "soccer" という語に完全一致するカテゴリを少なくとも1つ持つ (OR 検索) エントリを全て取得できます。
148
149::
150
151  GET /api.php/feeds/example/-/-baseball HTTP/1.1
152  Host: example.com
153
154このリクエストでは、"baseball" という語に完全一致するカテゴリを持たないエントリを全て取得できます。
155
156この表記による category クエリを用いる場合は、他のクエリをカテゴリ記述の後に付加します。
157
158::
159
160  GET /api.php/feeds/example/-/baseball/-soccer?q=term HTTP/1.1
161  Host: example.com
162
163このリクエストでは、"baseball" というカテゴリを持ち、"soccer" というカテゴリを持たず、コンテンツに "term" という語を含むエントリを全て取得できます。
164
165.. _category-request-parameter:
166
167category=value 表記
168+++++++++++++++++++
169
170category クエリでもカテゴリによる検索をおこなうことができます。
171
172::
173
174  GET /api.php/feeds/example?category=baseball HTTP/1.1
175  Host: example.com
176
177このリクエストでは、"baseball" という語に完全一致するカテゴリを持つエントリを全て取得できます。
178
179::
180
181  GET /api.php/feeds/example?category=baseball%2Cjapan HTTP/1.1
182  Host: example.com
183
184%2C は半角カンマ文字 (,) を URL-encode したものです。このリクエストでは、"baseball" と "japan" という語に完全一致するカテゴリを全て持つ (AND 検索) エントリを全て取得できます。
185
186::
187
188  GET /api.php/feeds/example?category=baseball%7Csoccer HTTP/1.1
189  Host: example.com
190
191このリクエストでは、"baseball" と "soccer" という語に完全一致するカテゴリを少なくとも1つ持つ (OR 検索) エントリを全て取得できます。
192
193この表記では、カテゴリを除外する指定はできません。
194
195著者や投稿日時などの条件による絞り込み検索
196------------------------------------------
197
198.. _author-query:
199
200author クエリ
201+++++++++++++
202
203このリクエストでは、エントリ著者の URI が "http://example.com/member/1" であるエントリを全て取得できます。
204
205::
206
207  GET /api.php/feeds/example?author=http://example.com/member/1 HTTP/1.1
208  Host: example.com
209
210author クエリの値は、エントリ著者の URI に対して完全一致検索をします。
211
212.. _updated-query:
213
214updated-min / updated-max クエリ
215++++++++++++++++++++++++++++++++
216
217updated-min および updated-max クエリはエントリ更新日時の範囲を指定した検索をします。
218
219::
220
221  GET /api.php/feeds/example?updated-min=2009-02-01T06:00:00+09:00 HTTP/1.1
222  Host: example.com
223
224このリクエストでは、エントリ更新日時が 2009-02-01T06:00:00+09:00 以降のエントリを全て取得できます。
225
226::
227
228  GET /api.php/feeds/example?updated-max=2009-01-31T21:00:00+09:00 HTTP/1.1
229  Host: example.com
230
231このリクエストでは、エントリ更新日時が 2009-01-31T21:00:00+09:00 よりも前のエントリを全て取得できます。
232
233このパラメータ値は RFC 3339 タイムスタンプ形式に限ります。下限はその値を含み、上限はその値を含みません。
234
235.. _published-query:
236
237published-min / published-max クエリ
238++++++++++++++++++++++++++++++++++++
239
240published-min および published-max クエリはエントリ発行日時の範囲を指定した検索をします。
241
242::
243
244  GET /api.php/feeds/example?published-min=2009-02-01T06:00:00+09:00 HTTP/1.1
245  Host: example.com
246
247このリクエストでは、エントリ発行日時が 2009-02-01T06:00:00+09:00 以降のエントリを全て取得できます。
248
249::
250
251  GET /api.php/feeds/example?published-max=2009-01-31T21:00:00+09:00 HTTP/1.1
252  Host: example.com
253
254このリクエストでは、エントリ発行日時が 2009-01-31T21:00:00+09:00 よりも前のエントリを全て取得できます。
255
256このパラメータ値は RFC 3339 タイムスタンプ形式に限ります。下限はその値を含み、上限はその値を含みません。
257
258取得開始エントリ、取得件数の制限
259--------------------------------
260
261.. _start-query:
262
263start クエリ
264++++++++++++
265
266start クエリは取得を開始するエントリの番号を指定します。番号は 1 からはじまります。
267
268デフォルト値 1 が指定されています。
269
270::
271
272  GET /api.php/feeds/example?page=10 HTTP/1.1
273  Host: example.com
274
275このリクエストでは、 10 件目にヒットしたエントリから取得を開始します。
276
277.. _max-requests-query:
278
279max-results クエリ
280++++++++++++++++++
281
282max-results クエリは取得するエントリの最大数を指定します。
283
284この値はフィードサイズが大きくなりすぎないように、デフォルト値 25 が設定されています。
285
286::
287
288    GET /api.php/feeds/example?max-results=10 HTTP/1.1
289    Host: example.com
290
291このリクエストでは、(取得できるエントリ数が10件より多い場合) 1ページで取得するエントリ数を10件に制限できます。
292
293::
294
295    GET /api.php/feeds/example?max-results=500 HTTP/1.1
296    Host: example.com
297
298このリクエストでは、(取得できるエントリ数が500件以下の場合) 1ページで全件のエントリ (フィード全体) を取得できます。
299
300取得結果のソート
301----------------
302
303.. _orderby-query:
304
305orderby クエリ
306++++++++++++++
307
308orderby クエリは取得するリソースのソート順を決める要素を指定します。
309
310orderby パラメータ値は次のものが指定できます。
311
312* published : エントリの発行日時
313* updated : エントリの更新日時
314
315この値はデフォルト値 published が設定されています。
316
317::
318
319  GET /api.php/feeds/example?orderby=updated HTTP/1.1
320  Host: example.com
321
322このリクエストでは、更新日時が新しい順にエントリを取得できます。
323
324.. _sortorder-query:
325
326sortorder クエリ
327++++++++++++++++
328
329sortorder クエリは取得するリソースのソート順を指定します。
330
331sortorder パラメータ値は次のものが指定できます。
332
333* descend : 降順
334* ascend : 昇順
335
336この値はデフォルト値 descend が設定されています。
337
338::
339
340  GET /api.php/feeds/example?sortorder=ascend HTTP/1.1
341  Host: example.com
342
343このリクエストでは、発行日時が古い順にエントリを取得できます。
344
345エントリの取得
346==============
347
348.. image:: image/get_entry.png
349
350メンバ URI に対して GET することで、エントリを取得できます。
351
352::
353
354  GET /api.php/feeds/example/1 HTTP/1.1
355  Host: example.com
356
357レスポンスは以下のようになります。
358
359::
360
361  HTTP/1.1 200 Ok
362  Date: Sun, 01 Feb 2009 10:25:16 GMT
363  Content-Type: application/atom+xml; charset=utf-8
364 
365  <?xml version="1.0" encoding="UTF-8" ?>
366  <entry xmlns="http://www.w3.org/2005/Atom">
367    <id>http://example.com/example/1</id>
368    <published>2009-01-31T08:23:41+09:00</published>
369    <updated>2009-01-31T08:23:41+09:00</updated>
370    <title type="text">おはようございます</title>
371    <content type="text">今日はとても悪い天気です。</content>
372    <author>
373      <name>OpenPNE君</name>
374      <uri>http://example.com/member/1</uri>
375    </author>
376    <link rel="self" type="application/atom+xml" href="http://example.com/api.php/feeds/example/1"/>
377    <link rel="edit" type="application/atom+xml" href="http://example.com/api.php/feeds/example/1/1"/>
378    <link rel="alternate" type="text/html" href="http://example.com/example/1"/>
379    <link rel="alternate" href="http://example.com/mobile_frontend.php/example/1"/>
380  </entry>
381
382エントリの追加
383==============
384
385.. image:: image/post_entry.png
386
387コレクション URI に対して POST することで、エントリを追加できます。
388
389リクエストの例を以下に示します。
390
391::
392
393  POST /api.php/feeds/example HTTP/1.1
394  Host: example.com
395  Content-Type: application/atom+xml; charset=utf-8
396 
397  <?xml version="1.0" encoding="UTF-8" ?>
398  <entry xmlns="http://www.w3.org/2005/Atom">
399    <title type="text">おはようございます</title>
400    <content type="text">今日の天気は曇りです。</content>
401    <author>
402      <name>OpenPNE君</name>
403      <uri>http://example.com/member/1</uri>
404    </author>
405  </entry>
406
407レスポンスは以下のようになります。
408
409::
410
411  HTTP/1.1 201 Created
412  Date: Mon, 02 Feb 2009 00:13:50 GMT
413  Location: http://example.com/api.php/feeds/example/3
414  Content-Length: 695
415  Content-Type: application/atom+xml; charset=utf-8
416 
417  <?xml version="1.0" encoding="UTF-8" ?>
418  <entry xmlns="http://www.w3.org/2005/Atom">
419    <id>http://example.com/example/3</id>
420    <published>2009-02-02T09:13:51+09:00</published>
421    <updated>2009-02-02T09:13:51+09:00</updated>
422    <title type="text">おはようございます</title>
423    <content type="text">今日の天気は曇りです。</content>
424    <author>
425      <name>OpenPNE君</name>
426      <uri>http://example.com/member/1</uri>
427    </author>
428    <link rel="edit" type="application/atom+xml" href="http://example.com/api.php/feeds/example/3/1"/>
429    <link rel="alternate" type="text/html" href="http://example.com/example/3"/>
430    <link rel="alternate" href="http://example.com/mobile_frontend.php/example/3"/>
431  </entry>
432
433エントリの更新
434==============
435
436.. image:: image/put_entry.png
437
438メンバ URI に対して PUT することで、エントリを更新できます。
439
440リクエストの例を以下に示します。
441
442::
443
444  PUT /api.php/feeds/example/3/1 HTTP/1.1
445  Host: example.com
446  Content-Type: application/atom+xml; charset=utf-8
447 
448  <?xml version="1.0" encoding="UTF-8" ?>
449  <entry xmlns="http://www.w3.org/2005/Atom">
450    <id>http://example.com/example/3</id>
451    <title type="text">おはようございます</title>
452    <content type="text">
453  今日の天気は曇りです。
454 
455  追記:
456  午後に、土砂降りの雨が降りました。
457    </content>
458    <author>
459      <name>OpenPNE君</name>
460      <uri>http://example.com/member/1</uri>
461    </author>
462  </entry>
463
464レスポンスは以下のようになります。
465
466::
467
468  HTTP/1.1 200 Ok
469  Date: Mon, 02 Feb 2009 10:40:20 GMT
470  Content-Length: 782
471  Content-Type: application/atom+xml; charset=utf-8
472 
473  <?xml version="1.0" encoding="UTF-8" ?>
474  <entry xmlns="http://www.w3.org/2005/Atom">
475    <id>http://example.com/example/3</id>
476    <published>2009-02-02T09:13:51+09:00</published>
477    <updated>2009-02-02T19:40:21+09:00</updated>
478    <title type="text">おはようございます</title>
479    <content type="text">
480  今日の天気は曇りです。
481 
482  追記:
483  午後に、土砂降りの雨が降りました。
484    </content>
485    <author>
486      <name>OpenPNE君</name>
487      <uri>http://example.com/member/1</uri>
488    </author>
489    <link rel="edit" type="application/atom+xml" href="http://example.com/api.php/feeds/example/3/1"/>
490    <link rel="alternate" type="text/html" href="http://example.com/example/3"/>
491    <link rel="alternate" href="http://example.com/mobile_frontend.php/example/3"/>
492  </entry>
493
494エントリの削除
495==============
496
497.. image:: image/delete_entry.png
498
499メンバ URI に対して DELETE することで、エントリを削除できます。
500
501リクエストの例を以下に示します。
502
503::
504
505  DELETE /api.php/feeds/example/2 HTTP/1.1
506  Host: example.com
507
508レスポンスは以下のようになります。
509
510::
511
512  HTTP/1.1 200 Ok
513  Date: Mon, 02 Feb 2009 20:05:18 GMT
Note: See TracBrowser for help on using the repository browser.