FrontPage

API利用ガイド

事前情報の取得

IMD食品栄養データAPIの使用に当たっては、以下の各設定情報が必要となる。
(※使用に際し弊社より発行し、別途通知します)

APIサーバー名・アクセスコード

APIのエントリポイントは、サーバー名とアクセスコードを使用して構成する。

APIタイプURL
データ系APIhttps://(サーバー名)/services/api2/(アクセスコード)/(エントリ)

アクセス認証

APIを利用する上で正しいアクセス元であることを確認するため、アクセス元IPアドレスの制限、Authorizationヘッダーの送出、のいずれかまたは両方が必要である。

アクセス元IPアドレスの制限

APIはIPアドレスによってアクセスを制限する。使用に際しては、アクセス元となるIPアドレスを設定する必要がある。(※弊社にて設定しますのでアドレスをお知らせ下さい)

Authorizationヘッダーの送出

APIはAuthorizationヘッダーによってアクセスを認証する。クライアントは全てのアクセスに際して、HTTPリクエストヘッダーに以下の通りアクセストークンを送出する。(※弊社にてトークンを振りだしますのでご連絡ください)
アクセストークンは、他者に漏れないよう、正しく管理されなければならない。

Authorization: Bearer (アクセストークン)

Authorizationヘッダーは、typeをBearerとし、credentialsにアクセストークン文字列を指定する。アクセストークンについてはOAuth2.0の仕様に準じ、長さ不定の半角英数記号による文字列とする。
アクセストークンによる認証が成功した場合、HTTPレスポンスコード200を返却する。レスポンスヘッダーに X-MobadaiApi-Authenticated が含まれ、値は true となる。
アクセストークンによる認証に失敗した場合、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証明書

httpsのSSL証明書には、Let's Encryptを使用する。発行者の署名を確認する必要がある場合には、Let's Encrypt のページからca-certificateを取得できる。

APIへのアクセス

使用可能なメソッド

メソッドはGETを使用する。

必須のリクエストヘッダ

以下のリクエストヘッダは必ず送出しなければならない。

Host: (アクセスするAPIのホスト名)

アクセストークンによる認証を用いる場合、以下のリクエストヘッダは必ず送出しなければならない。

Authorization: (type) (credentials)

文字コード

APIで使用する文字コードはUTF-8とする。

ハッシュ値

API中でのハッシュ値の表記は、半角英数0-9a-fを用い、文字列とする。

例: dc7faf3c5cd4a3d5e67a6c53ac919667d748969c

オブジェクトID

API中でのオブジェクトIDの表記は、プレフィックスは"FO"、以降は半角英数0-9a-fを用い、文字列とする。

例: FO31e1a7b94566d0586903a90a

日付

日付の書式は次の通りとし、タイムゾーンはJSTを用いる。

"YYYY/MM/DD"
YYYY: 4桁で表記する西暦
MM: 2桁で表記する月(01-12)
DD: 2桁で表記する日(01-31)

日付時刻

日付時刻の書式は次の通りとし、タイムゾーンは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)

検索文字列ルール

  • 英字・数字は半角を用いる(全角英数字は使用されない)
  • カナは全角を用いる(半角カナは使用されない)
  • 英文字は大文字を用いる(英小文字は使用されない)
  • 次の半角記号は用いない
    <>?_,./\;:][+*}{`~=^-)('%$#"!&
  • 次の全角記号、全角機種依存文字は用いない
    〇○◇□△▽☆●◆■▲▼★◎◯♂♀〒()
    〔〕[]{}〈〉《》「」『』【】‘’“”
    →←↑↓⇒⇔…‥、。,.・:;?!゛゜´
    `¨^ヽヾゝゞ〃°′″¥$¢£%‰℃Å+
    -±×÷=≒≠≦≧<>≪≫∞∽∝∴∵∈∋
    ⊆⊇⊂⊃∪∩∧∨¬∀∃∠⊥⌒∂∇≡√∫∬
    ─│┌┐┘└├┬┤┴┼━┃┏┓┛┗┣┳┫
    ┻╋┠┯┨┷┿┝┰┥┸╂#&*@§※〓♯
    ♭♪†‡¶仝~ ̄_―‐∥|/\
    №㏍℡㊤㊥㊦㊧㊨㈱㈲㈹㍾㍽㍼㍻㍉㎜㎝㎞㎎
    ㎏㏄㍉㌔㌢㍍㌘㌧㌃㌶㍑㍗㌍㌦㌣㌫㍊㌻①②
    ③④⑤⑥⑦⑧⑨⑩⑪⑫⑬⑭⑮⑯⑰⑱⑲⑳ⅠⅡ
    ⅢⅣⅤⅥⅦⅧⅨⅩ
  • 絵文字は用いない

返値

HTTPレスポンスコード

エラー時等、アクセスの条件、状態に応じて、返却されるHTTPレスポンスコードは以下の通り。

代表的な状況HTTPレスポンスコード
IPアドレス制限による拒否403
アクセストークンによる拒否401
URL又はフォーマット誤り404
アクセスコード誤り404
検索結果が存在しない200
オブジェクトが存在しない200
設定により使用が拒否されている404
システムの内部的エラー等500

IPアドレス制限によってアクセスが拒否されている場合

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

アクセストークンによってアクセスが拒否されている場合

アクセストークンによってアクセスが拒否されている場合は、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またはアクセスコードが間違っている

アクセスしている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

クエリー文字列の誤り

クエリー文字列の誤り(禁止文字が含まれる等)の場合は、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

検索結果が存在しない

検索した結果の数が0の場合は、HTTPレスポンスコード200かつ結果が空のjsonがレスポンスボディに返却される。

例:
$ curl -I "https://apiserver-mycode.mobadai.jp/services/api2/mycode/search/custom/json/カぬレま8ー/0/50/"
HTTP/1.1 200 OK
Date: Wed, 09 Dec 2020 20:53:58 GMT
Server: Apache
Content-Length: 12

オブジェクトが存在しない

オブジェクトが存在しない場合は、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

エラー情報を含むjsonの書式は以下の通り。

{
 "v":1,
 "errcd":"(エラー情報)"
}
エラー情報内容
invalidcharクエリーに使用できない文字が含まれる

疎通確認

アクセスするAPIサーバーのトップレベルに引数なしでアクセスした場合、動作していればjsonを返却するので、疎通確認に使用できる。IPアドレス制限の状態及びAPIサーバー名の確認が可能である。

例:
$ curl https://apiserver-mycode.mobadai.jp/
{"result":false,"reason":"unknown cmd :","product_version":"20200720-1"}

返却フォーマット

jsonを使用する。


トップ   リロード   一覧 単語検索 最終更新   ヘルプ   最終更新のRSS
Last-modified: 2020-12-24 (木) 09:21:44 (145d)