LINE WORKS API 共通仕様

ここでは、LINE WORKS API の共通仕様について説明します。

提供されるすべての API は、REST 形式で、HTTPS を経由してAPIエンドポイントに接続します。

認証 {#authorization}

API の呼び出しには Access Token が必要です。取得した Access Token は、認証スキーム Bearer と組み合わせて Authorization HTTP Request Header に指定し、API を呼び出します。

Authorization: Bearer {Access Token}

注意
Authorization タイプに Bearer を明示し、Bearer と Token を 1 つの半角スペースでつなぎます。

Access Token を取得する方法は 2 種類あります。詳しくは認証を参照してください。

API エンドポイント {#api-endpoint}

LINE WORKS API を呼び出す際にアクセスするエンドポイント (URL) は以下の通りです。

https://www.worksapis.com/v1.0/...

例として GET メソッドで Bot リストを取得する場合は以下の形式です。

GET https://www.worksapis.com/v1.0/bots

HTTPメソッド {#http-method}

すべての API の呼び出しは、HTTP メソッドと URL の組み合わせです。 HTTP メソッドは該当するリソースの操作 (何をするか) を表すもので、LINE WORKS API では以下の HTTP メソッドを使用します。

GET : リソースの取得
- リソースの取得や、ファイルをダウンロードする API に使用されます。
POST : リソースの登録
- リソースの登録や Bot メッセージ送信、ファイルアップロードなどのフォームデータを送信する API に使用されます。
- リクエスト内容はリクエストボディに指定します。
- POST リクエストがオブジェクトの登録に利用された場合には、通常は登録されたオブジェクトがレスポンスボディに返されます。
PUT : リソースの更新
- リソースの置き換えなど、データを更新する API に使用されます。
- PUT リクエストでは、リソースはリクエストボディに指定した値で置き換えられます。
  - 注意
    リクエストボディに指定されなかったプロパティは、既定値で置き換えられるか、null 値を指定したものとして取り扱われて値が失われます。
- 通常は、更新後のオブジェクトがリクエストボディに返されます。
PATCH : リソースの部分更新
- リソースの一部を更新する API に使用されます。
- PATCH リクエストでは、リクエストボディで指定したプロパティのみが置き換えられ、指定しなかったプロパティは値が保持されます。
- 通常は、更新後のオブジェクトがリクエストボディに返されます。
DELETE : リソースの削除
- リソースを削除する API に使用されます。

補足: PUT と PATCH
PUT メソッドは、リソースの全てのプロパティを変更する際に利用します。未指定のプロパティは既定値に置き換えられます。
PATCH メソッドは、リソースの一部のプロパティを変更する際に利用します。指定したプロパティのみ変更され、未指定のプロパティは変更されません。
リソースの一部のプロパティのみを更新する場合には、変更したいプロパティのみを指定する PATCH メソッドの利用を推奨します。

パラメータ {#request-parameter}

同じ API でも、指定するパラメータにより、動作が異なります。
API を呼び出す際に指定できるパラメータには、リソースを指定する Path パラメータ、その他の API の挙動をコントロールする Query パラメータ、主にオブジェクトのプロパティの指定に使用されるリクエストボディRequest Body などがあります。

注意
Path パラメータと Query パラメータは、URL エンコードして指定します。

注意
必ずドキュメントに定義されたパラメータ・プロパティを使用してください。ドキュメントに定義されていないパラメータ・プロパティを使用すると、エラーや意図しない動作を引き起こす可能性があります。

Path パラメータ {#path-parameter}

特定のリソースを取り扱う API を呼び出す際には、操作の対象となるリソースを識別するためのパラメータを API リクエスト URL の Path パラメータ に含めます。Path パラメータ は必ず指定する必要がある必須パラメータです。
API リファレンスでは、{parameter} として記載されています。
例えば、特定のユーザーのユーザー情報は、以下の API を呼び出すことで取得できます。

GET /v1.0/users/{userId}

この時、{userId} には、以下のいずれかの値を指定します。

ユーザー ID (userId)
- 例 : userf7da-f82c-4284-13e7-030f3b4c756x
ログイン ID (email)
- 例 : user@domain
External Key (externalKey)
- 例 : externalKey:ExternalKeyValue

注意
API リファレンスでは、ExternalKey の指定方法は externalKey:{userExternalKey} と記載されています。
{userExternalKey} を実際の ExternalKey の値 ExternalKeyValue と置き換え、externalKey:ExternalKeyValue と指定します。

ユーザー ID を指定した場合には、以下の URL が API のリクエスト URL となります。

GET /v1.0/users/userf7da-f82c-4284-13e7-030f3b4c756x

指定できる値は API により異なります。それぞれの API リファレンスを参照してください。

me キーワード {#me-keyword}

一部の API では path パラメータの {userId} として me キーワードを利用できます。me キーワードを利用すると、認証されたユーザーのリソースに対して API が呼び出されます。例えば、ログインしたユーザーの {userId} を利用する場合には、下記の API リクエストでは同じレスポンスが取得できます。

GET /v1.0/users/me
GET /v1.0/users/{userId}

注意
サービスアカウントを利用した JWT 認証を行ったトークンでは、me キーワードは利用できません。

Query パラメータ {#query-parameter}

Query パラメータは、リソースの指定ではないが、API の動作を指定する場合に用いられます。Query パラメータには、必須パラメータであるものと、必須パラメータではないものがあります。それぞれの API リファレンスを確認してください。

Query パラメータの例として、リスト取得における取得数 count やカーソル値 cursor などが挙げられます。
Query パラメータは、リクエスト URLに "?" を付加して、パラメータ名と値を "=" でつないで指定します。複数の Query パラメータを指定する場合には、"&" でつなげます。

以下は、ドメイン domainId と取得数 count を指定してユーザーリストを取得する API の例です。

GET /v1.0/users?domainId=10000001&count=20

リクエストボディ/レスポンスボディ {#request-response-body}

POST、PUT、PATCH メソッドのリクエストボディおよびレスポンスボディのコンテンツタイプは JSON (JavaScript Object Notation) を利用します。文字コードは UTF-8 です。
Header には以下の Content-Type を指定します。

Content-Type: application/json; charset=UTF-8

注意
一部の API では、JSON 以外の形式を利用しています。詳しくは、各 API リファレンスを参照ください。

JSON 形式 {#json-format}

ここでは、JSON の概要について記載します。

JSON は、オブジェクトは "{" と "}" で囲い、その中にプロパティ名と値を記述します。プロパティ名は """ (ダブルコーテーション) で囲い、":" を挟んで値を記述します。また、プロパティやオブジェクトは、"," で区切ります。

文字列 {#json-string}

文字列は、""" (ダブルコーテーション) で囲みます。

{  "string" : "文字列"}

数値 {#json-number}

数値は、そのまま記述します。

{    "number"  : 12345}

Bool 値と NULL {#json-bool-and-null}

boolean (True/False) と NULL は、いずれも """ (ダブルコーテーション) で囲まずに、小文字で ture、false、または null と記載します。

{  "bool-true" : true,  "bool-false" : false,  "null" : null}

入れ子 {#json-nest}

オブジェクトを入れ子にする場合には、"{" と "}" で囲んだオブジェクトを記載できます。

{  "object" : {    "property1" : "value1",    "property2" : "value2"  }}

配列 {#json-array}

"[" と "]" の中に、複数のオブジェクト、または値を含めて配列にできます。

{  "ObjectArray" : [    {      "object" : "1st object"    },    {      "object" :  "2nd object"    }  ],  "ValueArray" : [    "ValueA",    "ValueB"  ]}

JSON では、プロパティやオブジェクトの順序は意味を持ちません。また、スペースやタブ、改行も意味を持ちません。
このため、以下の 2 つの記載は、同じ意味となります。

{  "Property1" : 1,  "Property2" : 2}

{"Property2":2,"Property1":1}

レスポンスヘッダー {#response-header}

レスポンスヘッダーのフィールド名は大文字小文字を区別せずに扱ってください。表記が予告なく変更される可能性があります。

参考: https://www.rfc-editor.org/rfc/rfc9110#section-5.1

ステータスコード {#status-code}

リクエストの結果は、レスポンスに含まれるステータスコードで判別します。

API の呼び出しが成功すると、通常は、単に成功を示す 2xx か、リダイレクトを示す 3xx が返されます。
一方、API の呼び出しが失敗すると、通常は、クライアントからのリクエストが原因であることを示す HTTP Status Code 4xx か、サーバーエラーを示す HTTP Status Code 5xx が返されます。

API の呼び出しに対する主な HTTP Status Code を以下に示します。

Status Code	Reason Phrase
200	OK
202	Accepted
204	No Content
302	Found
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
429	Too Many Requests
500	Internal Server Error
503	Service Unavailable

エラーレスポンス {#error-response}

エラー発生時は、ボディに含まれるエラーオブジェクトで内容を確認します。

詳しくはエラーレスポンスを参照してください。

ページネーション {#pagination}

大量のリソースデータを取得する際は、「ページネーション」によって複数リクエストに分けて取得します。

詳しくはページネーションを参照してください。

ファイルアップロード / ダウンロード {#file-upload-download}

LINE WORKS API には、ファイルデータをアップロードまたはダウンロードする API がいくつか存在します。それぞれのアップロード/ダウンロードの方式は共通化されています。

詳しくはファイルアップロード/ダウンロードを参照してください。

API の呼び出しの上限 {#call-limitation}

サービス安定化のため、APIの呼び出しには、Rate Limit と 同時接続数 の2種類の上限値が設けられています。上限を超えたリクエスト行われると、一時的に呼び出しが制限されてエラーを返します。

詳細は API 使用の上限を参照してください。

API 呼び出しの確認 {#check-api-call}

API を利用したリソースの変更は、該当する各サービスの監査ログへ記録されます。ログは管理者画面の監査メニューから確認できます。また、Developer Console > API > Statistics で、API 呼び出しの利用統計情報を確認できます。

その他 {#appendix}

その他の補足情報は付録を参照してください。