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

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

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

added some urls to references

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