雑記

すぐ呼び出し可能なWebAPIのサンプル

2020/12/27

この記事が対象とする製品・バージョン

HTTPリクエストを送信できるすべての言語・製品が対象です。

１．概要
２．利用条件
３．利用例
４．共通仕様
５．API仕様
６．データ
- ６－１．person

１．概要

どこからでも簡単に呼び出せるREST WebAPIのサンプルです。このサービスは架空の人物名簿で、人物を取得したり、追加、更新、削除ができます。プログラムの練習やお試しに使用することを想定しています。

下記の利用条件を守ってください。

２．利用条件

・いつ、誰が呼び出しても良いです。

・大量に呼び出さないでください。

たとえば、これを使って性能テストなどしないでください。１日1000回くらいは呼び出しても大丈夫ですが、何人が利用するかわからないので１人当たり何回とは書き難いです。１日あたり10回、20回程度なら余裕だと思います。

※2021/1/24現在、公開からこれまで約1ヶ月で合計で200回くらいしか呼び出されていません。もっと呼び出しても大丈夫です。

・誰かが不愉快になる内容を送信しないでください。追加・更新した内容は、他の人からも見えます。

・稼動や品質に保証はありません。

呼び出しやすいように利用条件はかなりゆるく設定しています。様子を見て、大量の負荷がかかったり、私の運用の手間がかかったりするようであれば条件を厳しく見直すか、最悪公開停止にします。節度を守ってご利用ください。

３．利用例

次のHTTP GET リクエストを送信すると登録されている人物 Shakespear (シェークスピア)の情報を取得できます。

https://umayadia-apisample.azurewebsites.net/api/persons/Shakespeare

一番簡単に試す方法はブラウザーのアドレスバーにこのURLを入力することです。

次のようなレスポンスを受け取ります。

{"success":true,"data":{"name":"Shakespeare","note":"Hamlet","age":13,"registerDate":"1564-04-26T20:21:00"}}

プログラムでShakespearの情報を取得することもできます。プログラム言語に制限はありません。ここではVBとC#の場合の例を載せます。

環境によっては NuGet で System.Net.Http をインストールする必要があるかもしれません。→ その方法

Dim url As String = "https://umayadia-apisample.azurewebsites.net/api/persons/Shakespeare"

Using client As New System.Net.Http.HttpClient()
    Using response As System.Net.Http.HttpResponseMessage = client.GetAsync(url).Result
        Dim responseBody As String = response.Content.ReadAsStringAsync().Result
        Debug.WriteLine(responseBody)
    End Using
End Using

→ Debug.WriteLineで出力される場所

string url = "https://umayadia-apisample.azurewebsites.net/api/persons/Shakespeare";

using (System.Net.Http.HttpClient client = new System.Net.Http.HttpClient())
{
    using (System.Net.Http.HttpResponseMessage response = client.GetAsync(url).Result)
    {
        string responseBody = response.Content.ReadAsStringAsync().Result;
        System.Diagnostics.Debug.WriteLine(responseBody);
    }
}

→ Debug.WriteLineで出力される場所

４．共通仕様

４－１．概要

データはJSON形式で表現されます。

APIを公開しているURLは下記の通りです。

https://umayadia-apisample.azurewebsites.net/api/

すべてのAPIでこのURLは共通しており、この後ろにAPI個別のパスが続きます。

４－２．リクエスト

JSON形式のボディを持つリクエストは content-type に application/json を指定してください。

４－３．レスポンスの共通形式

正常なレスポンスはHTTPステータス 200で、次の項目を含みます。

項目	型	説明
success	false/true	リクエストが成功したことを示します。常に true です。
data	オブジェクト/null	リクエストに含まれるデータ。何のデータも含まない場合 null。

エラーレスポンスはHTTPステータス 500で、次の項目を含みます。

項目	型	説明
success	false/true	リクエストが失敗したことを示します。常に false です。
errorCode	文字列	エラーコード
errorMessage	文字列	エラーメッセージ

エラーレスポンスの例

{"success":false,"errorCode":"DE101","errorMessage":"足利尊氏は存在しないため削除できません。"}

正常レスポンスとエラーレスポンスとで success が共通するので、この値を見て、正常かエラーか判断できます。

想定外のエラーが発生した場合、JSON形式ではないエラー応答が返る場合もあります。

５．API仕様

APIの一覧

GET management	環境情報を取得します。
GET persons	全人物の一覧を取得します。
GET persons/{name}	指定した人物の情報を取得します。
POST persons	人物を新規に登録します。
PUT persons/{name}	人物の情報を更新します。
DELETE persons/{name}	人物を削除します。
DELETE persons/all/reset	すべての登録情報を初期状態に戻します。
OPTIONS persons	利用可能なAPIの一覧を取得します。

GET management

このAPIの環境情報を取得します。現在のところバージョン情報のみです。

リクエストURL

https://umayadia-apisample.azurewebsites.net/api/management

HTTPメソッド

GET

リクエスト本文

(このAPIにはリクエスト本文はありません。)

リクエスト本文の例

(このAPIにはリクエスト本文はありません。)

レスポンス本文

レスポンス本文のdataには次のオブジェクトが返されます。

レスポンス全体は、レスポンスの共通形式を参照してください。

項目	型	説明
version	文字列	1.0 のような形式でこのAPIのバージョンを返します。

レスポンス本文全体の例

{"success":true,"data":{"version":"1.0"}}

GET persons

登録されている全人物の情報を取得します。

リクエストURL

https://umayadia-apisample.azurewebsites.net/api/persons

HTTPメソッド

GET

リクエスト本文

(このAPIにはリクエスト本文はありません。)

リクエスト本文の例

(このAPIにはリクエスト本文はありません。)

レスポンス本文

レスポンス本文のdataには次のオブジェクトが返されます。

レスポンス全体は、レスポンスの共通形式を参照してください。

項目	型	説明
	personオブジェクトの配列 ※personオブジェクトの定義は、データを参照してください。	登録されている全人物の情報

レスポンス本文全体の例

{"success":true,"data":[{"name":"織田信長","note":"本能寺の変","age":12,"registerDate":"1534-07-03T04:14:25"},{"name":"Shakespeare","note":"Hamlet","age":13,"registerDate":"1564-04-26T20:21:00"},{"name":"聖徳太子","note":"法隆寺","age":21,"registerDate":"0574-02-07T23:41:35"},{"name":"Kennedy","note":"the 35th president of the United States","age":32,"registerDate":"1917-05-29T15:18:49"},{"name":"నాగార్జునుడు","note":"గాంచిన బౌద్ధ ధర్మ తాత్వికుడు. ","age":32,"registerDate":"0150-01-01T00:00:00"}]}

GET persons/{name}

{name}で指定された人物の情報を取得します。

リクエストURL

https://umayadia-apisample.azurewebsites.net/api/persons/{name}

{name}の部分は人物の名前に置き換えてください。

例

Shakespeare(シェークスピア)の情報を取得する場合

https://umayadia-apisample.azurewebsites.net/api/persons/Shakespeare

織田信長の情報を取得する場合

https://umayadia-apisample.azurewebsites.net/api/persons/%E7%B9%94%E7%94%B0%E4%BF%A1%E9%95%B7

漢字のような非ACSII文字の名前はURLエンコードして指定してください。

※ただし、ブラウザーやプログラミングのライブラリーにはこの変換を自動的に行ってくれるものもがあるので、使用するときに意識しなくて良いかもしれません。

HTTPメソッド

GET

リクエスト本文

(このAPIにはリクエスト本文はありません。)

リクエスト本文の例

(このAPIにはリクエスト本文はありません。)

レスポンス本文

指定した人物が存在する場合、レスポンス本文のdataには次のオブジェクトが返されます。

レスポンス全体は、レスポンスの共通形式を参照してください。

項目	型	説明
	personオブジェクト ※personオブジェクトの定義は、データを参照してください。	人物の情報

指定した人物が存在しない場合、dataはnullです。

レスポンス本文全体の例

{"success":true,"data":{"name":"織田信長","note":"本能寺の変","age":12,"registerDate":"1534-07-03T04:14:25"}}

POST persons

新規に人物を登録します。

リクエストURL

https://umayadia-apisample.azurewebsites.net/api/persons

HTTPメソッド

POST

リクエスト本文

personオブジェクト。

※personオブジェクトの定義は、データを参照してください。

リクエスト本文の例

{"name":"卑弥呼","note":"邪馬台国","age":75,"registerDate":"0214-03-03T04:14:25"}

レスポンス本文

レスポンス本文のdataは常に null です。

レスポンス全体は、レスポンスの共通形式を参照してください。

レスポンス本文全体の例

{"success":true,"data":null}

PUT persons/{name}

{name}で指定された人物の情報を更新します。

対象の人物は登録済みである必要があります。新規に人物を登録するには POST persons/{name} を使用します。

一部の人物は保護されており更新できません。

リクエストURL

https://umayadia-apisample.azurewebsites.net/api/persons/{name}

{name}の部分は人物の名前に置き換えてください。

例

Shakespeare(シェークスピア)の情報を更新する場合

https://umayadia-apisample.azurewebsites.net/api/persons/Shakespeare

織田信長の情報を更新する場合

https://umayadia-apisample.azurewebsites.net/api/persons/%E7%B9%94%E7%94%B0%E4%BF%A1%E9%95%B7

漢字のような非ACSII文字の名前はURLエンコードして指定してください。

HTTPメソッド

PUT

リクエスト本文

personオブジェクト。{name}で指定された人物の情報をこのpersonオブジェクトの情報で置き換えます。

※personオブジェクトの定義は、データを参照してください。

リクエスト本文の例

{"name":"Kennedy","note":"UPDATE NOTE!","age":32,"registerDate":"1917-05-29T15:18:49"}

レスポンス本文

レスポンス本文のdataは常に null です。

レスポンス全体は、レスポンスの共通形式を参照してください。

レスポンス本文全体の例

{"success":true,"data":null}

DELETE persons/{name}

{name}で指定された人物の情報を削除します。

一部の人物は保護されており削除できません。

リクエストURL

https://umayadia-apisample.azurewebsites.net/api/persons/{name}

{name}の部分は人物の名前に置き換えてください。

例

Kennedy(ケネディ)を削除

https://umayadia-apisample.azurewebsites.net/api/persons/Kennedy

武田信玄を削除する場合

https://umayadia-apisample.azurewebsites.net/api/persons/%E6%AD%A6%E7%94%B0%E4%BF%A1%E7%8E%84

漢字のような非ACSII文字の名前はURLエンコードして指定してください。

HTTPメソッド

DELETE

リクエスト本文

(このAPIにはリクエスト本文はありません。)

リクエスト本文の例

(このAPIにはリクエスト本文はありません。)

レスポンス本文

レスポンス本文のdataは常に null です。

レスポンス全体は、レスポンスの共通形式を参照してください。

レスポンス本文全体の例

{"success":true,"data":null}

DELETE persons/all/reset

すべての登録内容を初期状態に戻します。

リクエストURL

https://umayadia-apisample.azurewebsites.net/api/persons/all/reset

HTTPメソッド

DELETE

リクエスト本文

(このAPIにはリクエスト本文はありません。)

リクエスト本文の例

(このAPIにはリクエスト本文はありません。)

レスポンス本文

レスポンス本文のdataは常に null です。

レスポンス全体は、レスポンスの共通形式を参照してください。

レスポンス本文全体の例

{"success":true,"data":null}

OPTIONS persons

APIの一覧を取得します。

リクエストURL

https://umayadia-apisample.azurewebsites.net/api/persons

HTTPメソッド

OPTIONS

リクエスト本文

(このAPIにはリクエスト本文はありません。)

リクエスト本文の例

(このAPIにはリクエスト本文はありません。)

レスポンス本文

レスポンス本文のdataには次のオブジェクトが返されます。

レスポンス全体は、レスポンスの共通形式を参照してください。

項目	型	説明
	文字列の配列	APIの一覧

レスポンス本文全体の例

{"success":true,"data":["GET api/<PersonsController> :すべての人物の一覧を取得します。","GET api/<PersonsController>/{name} :{name}で指定された人物を取得します。","POST api/
<PersonsController> :人物を追加します。ボディにJSON形式で人物を指定します。","PUT api/<PersonsController>/{name} :{name}で指定された人物を変更します。ボディにJSON形式で変更後の人物の値を指定します。","DELETE api/<PersonsController>/{name} :{name}で指定された人物を削除します。","DELETE api/<PersonsController>/all/reset :すべての人物を初期状態に戻します。すべての変更は失われます。","OPTIONS api/<PersonsController> :personsに対して有効なメソッドの一覧を取得します。"]}

６．データ

６－１．person

人物情報を表します。

項目	型	説明
name	文字列	人物の名前です。最大20文字。
note	文字列	人物に関するメモ。最大100文字。
age	数値	人物の年齢。※このAPIは架空の情報を登録しており年齢は根拠のない適当な数値です。
registerDate	文字列(日付)	データの登録日。※この項目はサンプルであり、適当な日付が登録されています。 1917-05-29T15:18:49 のような形式です。

JSONでの表現例

{"name":"Kennedy","note":"the 35th president of the United States","age":32,"registerDate":"1917-05-29T15:18:49"}