エンジニアはこわくない

好きなように書く

トップ > プログラム > IBM WatsonのAPIガイドラインを読んでREADME部分を翻訳してみました

IBM WatsonのAPIガイドラインを読んでREADME部分を翻訳してみました

プログラム プログラム-IBM

スポンサーリンク

f:id:tsujitaku50:20170429192343p:plain

こんにちは、つじたく（@Tsuji_Taku50）です。

Watson Developer Cloud · GitHubを眺めていると、WatsonのApi Guidelinesがリポジトリとしては存在していたので

主にREADMEの部分をGoogle翻訳と自分なりに意訳してみました。

README部分の全ての訳したわけではなく、少し飛ばした部分もありますが8割ほどは訳したつもりです。

間違っている部分も多々あると思いますが、ご勘弁を。

リポジトリ

下記が公式のApi Guidelinesリポジトリです。

github.com

翻訳してみる

ネーミングについて

全ての変数名は「スネークケース」を使用して、略語や略語は使用しないでください。

  • 良い例
classifier_id
status_description
generate_visualization
  • 悪い例
observeResult
lang
DateRange
vad_score
  • 例外

言語コードの確立された規約がある場合、これらを使用します

en、en-us

JSON vs CSV vs XML

APIはバイナリ以外のデータの入出力にJSONをサポートする必要があります。

Content-Type（入力用）およびAccept（出力用）ヘッダーを使用してフォーマットを指定することで、CSVまたはXMLをサポートできます。

形式を指定しないと、デフォルトでJSONに設定されます。

JSON構造

APIはトップレベルの匿名配列を使用すべきではありません。

JSONオブジェクトに配列をラップすることで、後でフィールドを追加することができます。

  • 良い例
{"items": ["item 1", "item 2"]}
  • 悪い例
["item 1", "item 2"]

動的キーを避ける

JSONオブジェクトのキーは、動的なユーザー指定の値ではなく、静的な文字列である必要があります。

  • 良い例
{"user_key": "my user key", "user_value": "my user value"}
  • 悪い例
{"my user key": "my user value"}

複数の言語

APIが複数の言語（英語またはスペイン語など）でコンテンツをサポートしている場合、Content-Languageヘッダーフィールドを使用して言語を指定する必要があります。

たとえば、RFC 1766に準拠する言語値や「en」または「es-ES」です。

入力の複数の部分が複数の言語で記述できる入力データを処理する場合、 “language"のJSONフィールドを使用できます。

{"profiles": [{"text": "hello", "language": "en"}, {"text": "hola", "language": "es"}]}

ユーザーが作成したリソースについて

ユーザーによって作成されたリソースはpostで /resource_name, and accessed at /resource_name/resource_idの形になるべきである。

resource_idは、サービスによって生成されます。

resource_idとは

ユーザーが作成したリソースIDは、

  • サービスによって生成されます。

  • ユーザーによって指定されていないません。

  • グローバルに一意でなければなりません。

  • ユーザーに固有のものではありません

  • フレンドリで非一意の識別子の場合、リソースにはユーザー指定の「名前」フィールドが含まれている必要があります。

非同期操作

15秒以上かかる操作ではPOSTで初期化する必要があり、

新しく作成されたリソースのIDを返す必要があります。

例えば

POST https://gatway.watsonplatform.net/natural-language-classifier/classifiersでレスポンスをすると

{
  "classifier_id": "47C164-nlc-243",
  "name": "weather",
  "language": "en",
  "created": "2015-08-24T18:42:25.324Z",
  "url": "https://gateway.watsonplatform.net/natural-language-classifier/api/v1/classifiers/47C164-nlc-243",
  "status": "Training",
  "status_description": "The classifier instance is in its training phase, not yet ready to accept classify requests"
}

操作のステータスまたは結果（操作が完了したとき）を取得するには、次のようなURLを使用する必要があります。

GET https://gateway.watsonplatform.net/natural-language-classifier/api/v1/classifiers/47C164-nlc-243

非同期操作の結果が永続的なリソースではなく一時的なものである場合、ユーザーは取得後にリソースを削除する必要があります。↓

DELETE https://gateway.watsonplatform.net/natural-language-classifier/api/v1/classifiers/47C164-nlc-243

多言語サポート

言語コードは、入出力に “en"、 "en-US"として指定する必要があります。

指定されないままにしておくと、言語はデフォルトで “en"に設定されます。

入力言語を指定するには、標準のhttpヘッダーのcontent-languageをサポートする必要があります。

JSON入力の「言語」フィールドもサポートでき、ヘッダーよりも優先される必要があります。

日付

レスポンスに返される日付yyyy-MM-dd'T'HH:mm:ss.SSS'Z'はISO 8601を使用してフォーマットする必要があります。

レスポンスで返されるすべての日付/時刻はUTCタイムゾーンにある必要があります。

エラー

5xxエラーは、サーバーエラーと稼働時間障害のためだけに使用する必要があります。

誤った入力やサポートされていないユーザー入力が原因の場合は、4xxエラーを使用する必要があります。

エラーのJSONオブジェクト

サンプル例

{"code": 404, "error": "Not found"}

{"code": 400, "error": "Missing text", "description": "The required 'text' parameter is missing."}

GET vs POST vs PUT

  • GEtメソッドについて

    • GETメソッドは安全でなければありません。

    • 副作用を持ってはいけません。

    • 基底のリソースが変わるまで同じ結果を返すべきです。

  • POSTメソッドについて

    • 安全である必要はありませんが、クエリパラメータは避けるべきです。

    • 安全なメソッドは、〜4KBより大きいパラメータが必要な場合を除いて、GETを使用する必要があります。

  • PUTメソッドについて

    • PUTメソッドを同じパラメータで複数回呼び出すことは、一度呼び出すことと区別できないようにする必要があります。つまり何度PUTメソッドを読んでも同じ結果になる必要があります。

    • PUTメソッドもクエリパラメータを避ける必要があります。

共通APIの問題

GET vs POST vs PUT

すべてのGETメソッドは安全です。そしてPOSTコールはPOSTである必要がありますか？

引用符付きの数字

数値フィールドのいずれかが誤って文字列として返されていますか？

"value": "0.923" の代わりに "value": 0.923などなど

ネーミング

すべての識別子（リソース名、パラメータ名、JSONフィールド名）は頭字語や略語を使用せずにスネークケースを使用していますか？

匿名JSON配列

入力または出力のJSON構造にトップレベルの匿名配列が含まれている場合、

たとえば、{“items"：["item 1"、 "item 2”]の代わりに[item 1]、 “item 2”]を使用すると、後で拡張するのが難しくなります。

Watson Developer Cloud ガイドライン

ここから下記の部分は、IBM WatsonのDeveloper Cloud Servicesにのみ適用されます

バージョン管理

サービスには、メジャーバージョンがパスに含まれ、メジャーバージョンには/v1/必要なクエリパラメータとしてマイナーバージョンが含まれている必要があります。

このマイナーバージョンを使用してマイナーな改変の動作を制御することで、出力フィールド名、ステータスコード、またはその他の変更が行われたときに、ユーザーはバージョンを更新するまで影響を受けません。

開発者は現在の日付をバージョンとして渡すべきではなく、コードを書くときに最新のバージョンを使用し、定期的に変更をチェックし、コードとバージョンを更新して利用するべきです。

ここから先の部分はWatson Developer Cloudにのみ適用されるガイドラインだったので割愛etc

まとめ

READMEの部分以外にも

Code Styleだったり

Repository Guidelinesだったりが記載されているので

Watsonを使って何か作ろうかなと思っている人が一度目を通しおいても良いかもしれません。

おわり！！