- 追加された行はこの色です。
- 削除された行はこの色です。
- API利用ガイド へ行く。
#author("2022-06-13T10:27:45+09:00","","")
[[FrontPage]]
&size(24){API利用ガイド};
#contents
* 事前情報の取得 [#ae05b06f]
IMD食品栄養データAPIの使用に当たっては、以下の各設定情報が必要となる。~
（※使用に際し弊社より発行し、別途通知します）
** APIサーバー名・アクセスコード [#x9d809f5]
APIのエントリポイントは、サーバー名とアクセスコードを使用して構成する。
|APIタイプ|URL|h
|データ系API|https://(サーバー名)/services/api2/(アクセスコード)/(エントリ)|
** アクセス認証 [#p510b423]
APIを利用する上で正しいアクセス元であることを確認するため、アクセス元IPアドレスの制限、Authorizationヘッダーの送出、のいずれかまたは両方が必要である。
*** アクセス元IPアドレスの制限 [#pd81e71b]
APIはIPアドレスによってアクセスを制限する。使用に際しては、アクセス元となるIPアドレスを設定する必要がある。（※弊社にて設定しますのでアドレスをお知らせ下さい）
*** Authorizationヘッダーの送出 [#pd81e71b]
APIはAuthorizationヘッダーによってアクセスを認証する。クライアントは全てのアクセスに際して、HTTPリクエストヘッダーに以下の通りアクセストークンを送出する。（※弊社にてトークンを振りだしますのでご連絡ください）&br;
アクセストークンは、他者に漏れないよう、正しく管理されなければならない。
Authorization: Bearer (アクセストークン)
Authorizationヘッダーは、typeをBearerとし、credentialsにアクセストークン文字列を指定する。アクセストークンについてはOAuth2.0の仕様に準じ、長さ不定の半角英数記号による文字列とする。&br;
アクセストークンによる認証が成功した場合、HTTPレスポンスコード200を返却する。レスポンスヘッダーに X-MobadaiApi-Authenticated が含まれ、値は true となる。&br;
アクセストークンによる認証に失敗した場合、HTTPレスポンスコード401を返却する。レスポンスヘッダーに X-MobadaiApi-Authenticated は含まれない。
例:
$ curl -H 'Authorization: Bearer TVBJb3lvQ2VlbzlVVzZXNUFWZkladXhSVU5hcDQrREp1QWt6Z0hKM21qNU5OaEFsTnpvOXpWUDJ5TytKM0NXUjc2VEdTRG94RVRheVVScmZ6UGxHZzRmaDlqZm9HWm56cEZHTG4yUEx5eTRRWFFRLzlRelRSTmhtL3dLaW9OZU5aejBLS053cXV6bGdNQ0M4MVl4MXZmN21kRlFhQlhRd0pYMFBmZW95UXZkOTBNZ25HR2VPNGZ0Wk1CZmlPcTlJ' \
-I "https://yourserver.mobadai.jp/services/api2/yourcode/search/custom/json/SAMPLE/"
HTTP/1.1 200 OK
Date: Sun, 24 Feb 2019 23:48:58 GMT
Server: Apache
Vary: Authorization
X-MobadaiApi-Authenticated: true
Content-Length: *****
:
** httpsのSSL証明書 [#ye265ef0]
httpsのSSL証明書には、Let's Encryptを使用する。発行者の署名を確認する必要がある場合には、[[Let's Encrypt:https://letsencrypt.org/certificates/]] のページからca-certificateを取得できる。
* APIへのアクセス [#f12bbe0e]
** 使用可能なメソッド [#ve87dd44]
メソッドはGETを使用する。
** 必須のリクエストヘッダ [#l0690088]
以下のリクエストヘッダは必ず送出しなければならない。
Host: (アクセスするAPIのホスト名)
アクセストークンによる認証を用いる場合、以下のリクエストヘッダは必ず送出しなければならない。
Authorization: (type) (credentials)
** 文字コード [#z68ec85f]
APIで使用する文字コードはUTF-8とする。
** ハッシュ値 [#yc4fc25f]
API中でのハッシュ値の表記は、半角英数0-9a-fを用い、文字列とする。
例: dc7faf3c5cd4a3d5e67a6c53ac919667d748969c
** オブジェクトID [#yc4fc25f]
API中でのオブジェクトIDの表記は、プレフィックスは"FO"、以降は半角英数0-9a-fを用い、文字列とする。
例: FO31e1a7b94566d0586903a90a
** 日付 [#be833f76]
日付の書式は次の通りとし、タイムゾーンはJSTを用いる。
"YYYY/MM/DD"
YYYY: 4桁で表記する西暦
MM: 2桁で表記する月(01-12)
DD: 2桁で表記する日(01-31)
** 日付時刻 [#sb505a7d]
日付時刻の書式は次の通りとし、タイムゾーンはJSTを用いる。
"YYYY/MM/DD hh:mm:ss"
YYYY: 4桁で表記する西暦
MM: 2桁で表記する月(01-12)
DD: 2桁で表記する日(01-31)
hh: 2桁で表記する時(00-23)
mm: 2桁で表記する分(00-59)
ss: 2桁で表記する秒(00-59)
** 検索文字列ルール [#u55567aa]
- 英字・数字は半角を用いる（全角英数字は使用されない）
- カナは全角を用いる（半角カナは使用されない）
- 英文字は大文字を用いる（英小文字は使用されない）
- 次の半角記号は用いない
<>?_,./\;:][+*}{`~=^-)('%$#"!&
- 次の全角記号、全角機種依存文字は用いない
〇○◇□△▽☆●◆■▲▼★◎◯♂♀〒（）
〔〕［］｛｝〈〉《》「」『』【】‘’“”
→←↑↓⇒⇔…‥、。，．・：；？！゛゜´
｀¨＾ヽヾゝゞ〃°′″￥＄￠￡％‰℃Å＋
－±×÷＝≒≠≦≧＜＞≪≫∞∽∝∴∵∈∋
⊆⊇⊂⊃∪∩∧∨￢∀∃∠⊥⌒∂∇≡√∫∬
─│┌┐┘└├┬┤┴┼━┃┏┓┛┗┣┳┫
┻╋┠┯┨┷┿┝┰┥┸╂＃＆＊＠§※〓♯
♭♪†‡¶仝～￣＿―‐∥｜／＼
№㏍℡㊤㊥㊦㊧㊨㈱㈲㈹㍾㍽㍼㍻㍉㎜㎝㎞㎎
㎏㏄㍉㌔㌢㍍㌘㌧㌃㌶㍑㍗㌍㌦㌣㌫㍊㌻①②
③④⑤⑥⑦⑧⑨⑩⑪⑫⑬⑭⑮⑯⑰⑱⑲⑳ⅠⅡ
ⅢⅣⅤⅥⅦⅧⅨⅩ
- 絵文字は用いない
* 返値 [#rd31ae9b]
** HTTPレスポンスコード [#xec47999]
エラー時等、アクセスの条件、状態に応じて、返却されるHTTPレスポンスコードは以下の通り。
|代表的な状況|HTTPレスポンスコード|h
|IPアドレス制限による拒否|403|
|アクセストークンによる拒否|401|
|URL又はフォーマット誤り|404|
|アクセスコード誤り|404|
|検索結果が存在しない|200|
|オブジェクトが存在しない|200|
|設定により使用が拒否されている|404|
|システムの内部的エラー等|500|
*** IPアドレス制限によってアクセスが拒否されている場合 [#ia2e0d5e]
IPアドレス制限によってアクセスが拒否されている場合は、HTTPレスポンスコード403が返却される。
例:
$ curl -I "https://apiserver-mycode.mobadai.jp/services/api2/mycode/search/custom/json/カレー/0/50/"
HTTP/1.1 403 Forbidden
Date: Wed, 09 Dec 2020 20:51:11 GMT
Server: Apache
Content-Type: text/html; charset=iso-8859-1
*** アクセストークンによってアクセスが拒否されている場合 [#uc380c70]
アクセストークンによってアクセスが拒否されている場合は、HTTPレスポンスコード401が返却される。
例:
$ curl -I "https://apiserver-mycode.mobadai.jp/services/api2/mycode/search/custom/json/カレー/0/50/"
HTTP/1.0 401 Unauthorized
Date: Wed, 09 Dec 2020 23:24:28 GMT
Server: Apache
*** アクセスしているURLまたはアクセスコードが間違っている [#oda5f85e]
アクセスしているURL、アクセスコード、フォーマットが誤っている場合は、HTTPレスポンスコード404が返却される。
例:
$ curl -I "https://apiserver-mycode.mobadai.jp/service/api2/mycode/search/custom/json/カレー/0/50/"
HTTP/1.1 404 Not Found
Date: Wed, 09 Dec 2020 20:52:22 GMT
Server: Apache
Content-Type: text/html; charset=iso-8859-1
$ curl -I "https://apiserver-mycode.mobadai.jp/services/api2/mycobe/search/custom/json/カレー/0/50/"
HTTP/1.1 404 Not Found
Date: Wed, 09 Dec 2020 20:53:05 GMT
Server: Apache
Content-Type: text/html; charset=iso-8859-1
*** クエリー文字列の誤り [#bd65dbbf]
クエリー文字列の誤り（禁止文字が含まれる等）の場合は、HTTPレスポンスコード400が返却され、エラー情報を含むjsonがレスポンスボディに返却される。
例:
$ curl -I "https://api-kag-foodsearch2.mobadai.jp/services/api2/foodsearch/search/custom/json/カレー=そば/0/50/"
HTTP/1.1 400 Bad Request
Date: Wed, 09 Dec 2020 20:52:22 GMT
Server: Apache
Content-Length: 23
*** 検索結果が存在しない [#l55dc22e]
検索した結果の数が０の場合は、HTTPレスポンスコード200かつ結果が空のjsonがレスポンスボディに返却される。
例:
$ curl -I "https://apiserver-mycode.mobadai.jp/services/api2/mycode/search/custom/json/カぬレま８ー/0/50/"
HTTP/1.1 200 OK
Date: Wed, 09 Dec 2020 20:53:58 GMT
Server: Apache
Content-Length: 12
*** オブジェクトが存在しない [#a08b9efd]
オブジェクトが存在しない場合は、HTTPレスポンスコード200かつ空のjsonがレスポンスボディに返却される。
例:
$ curl -I "https://apiserver-mycode.mobadai.jp/services/api2/mycode/detail/json/FOf281333b5c6d0a6b329fba5c/"
HTTP/1.1 200 OK
Date: Wed, 09 Dec 2020 22:51:15 GMT
Server: Apache
Content-Length: 2
** エラー情報を含むjson [#jb7df444]
エラー情報を含むjsonの書式は以下の通り。
{
"v":1,
"errcd":"(エラー情報)"
}
|エラー情報|内容|h
|invalidchar|クエリーに使用できない文字が含まれる|
** 疎通確認 [#sda149b5]
アクセスするAPIサーバーのトップレベルに引数なしでアクセスした場合、動作していればjsonを返却するので、疎通確認に使用できる。IPアドレス制限の状態及びAPIサーバー名の確認が可能である。
例:
$ curl https://apiserver-mycode.mobadai.jp/
{"result":false,"reason":"unknown cmd :","product_version":"20200720-1"}
** 返却フォーマット [#zee1b52e]
jsonを使用する。
** 特殊文字 [#dc9e285f]
返却データ中、特殊文字は参照として表記される。参照は、文字実体参照または数値文字参照が使用される。クライアントでは、適切にデコードすることが望ましい。&br;
参考 [[文字参照:https://ja.wikipedia.org/wiki/%E6%96%87%E5%AD%97%E5%8F%82%E7%85%A7]] &br;
例
|&|アンパサンド| &amp; &#62; &#x3E; |
|'|シングルクォート| &apos; &#39; &#x27; |
|"|ダブルクオート| &quit; &#34; &#x22; |
|<|小なり記号| &lt; &#60; &#x3C; |
|>|大なり記号| &gt; &#62; &#x3E; |
![[PukiWiki]](image/pukiwiki.png "[PukiWiki]")
