雑記 |
Visual Basic 中学校 > 雑記 >
2020/12/27
この記事が対象とする製品・バージョン
HTTPリクエストを送信できるすべての言語・製品が対象です。目次
どこからでも簡単に呼び出せるREST WebAPIのサンプルです。このサービスは架空の人物名簿で、人物を取得したり、追加、更新、削除ができます。プログラムの練習やお試しに使用することを想定しています。
下記の利用条件を守ってください。
・いつ、誰が呼び出しても良いです。
・大量に呼び出さないでください。
たとえば、これを使って性能テストなどしないでください。1日1000回くらいは呼び出しても大丈夫ですが、何人が利用するかわからないので1人当たり何回とは書き難いです。1日あたり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 をインストールする必要があるかもしれません。→ その方法
VB
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 |
C#
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); } } |
データは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形式ではないエラー応答が返る場合もあります。
GET management | 環境情報を取得します。 |
GET persons | 全人物の一覧を取得します。 |
GET persons/{name} | 指定した人物の情報を取得します。 |
POST persons | 人物を新規に登録します。 |
PUT persons/{name} | 人物の情報を更新します。 |
DELETE persons/{name} | 人物を削除します。 |
DELETE persons/all/reset | すべての登録情報を初期状態に戻します。 |
OPTIONS persons | 利用可能なAPIの一覧を取得します。 |
このAPIの環境情報を取得します。現在のところバージョン情報のみです。
https://umayadia-apisample.azurewebsites.net/api/management
GET
(このAPIにはリクエスト本文はありません。)
(このAPIにはリクエスト本文はありません。)
レスポンス本文のdataには次のオブジェクトが返されます。
レスポンス全体は、レスポンスの共通形式を参照してください。
項目 | 型 | 説明 |
---|---|---|
version | 文字列 | 1.0 のような形式でこのAPIのバージョンを返します。 |
{"success":true,"data":{"version":"1.0"}} |
登録されている全人物の情報を取得します。
https://umayadia-apisample.azurewebsites.net/api/persons
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"}]} |
{name}で指定された人物の情報を取得します。
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エンコードして指定してください。
※ただし、ブラウザーやプログラミングのライブラリーにはこの変換を自動的に行ってくれるものもがあるので、使用するときに意識しなくて良いかもしれません。
GET
(このAPIにはリクエスト本文はありません。)
(このAPIにはリクエスト本文はありません。)
指定した人物が存在する場合、レスポンス本文のdataには次のオブジェクトが返されます。
レスポンス全体は、レスポンスの共通形式を参照してください。
項目 | 型 | 説明 |
---|---|---|
personオブジェクト ※personオブジェクトの定義は、データを参照してください。 |
人物の情報 |
指定した人物が存在しない場合、dataはnullです。
{"success":true,"data":{"name":"織田信長","note":"本能寺の変","age":12,"registerDate":"1534-07-03T04:14:25"}} |
新規に人物を登録します。
https://umayadia-apisample.azurewebsites.net/api/persons
POST
personオブジェクト。
※personオブジェクトの定義は、データを参照してください。
{"name":"卑弥呼","note":"邪馬台国","age":75,"registerDate":"0214-03-03T04:14:25"} |
レスポンス本文のdataは常に null です。
レスポンス全体は、レスポンスの共通形式を参照してください。
{"success":true,"data":null} |
{name}で指定された人物の情報を更新します。
対象の人物は登録済みである必要があります。新規に人物を登録するには POST persons/{name} を使用します。
一部の人物は保護されており更新できません。
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エンコードして指定してください。
※ただし、ブラウザーやプログラミングのライブラリーにはこの変換を自動的に行ってくれるものもがあるので、使用するときに意識しなくて良いかもしれません。
PUT
personオブジェクト。{name}で指定された人物の情報をこのpersonオブジェクトの情報で置き換えます。
※personオブジェクトの定義は、データを参照してください。
{"name":"Kennedy","note":"UPDATE NOTE!","age":32,"registerDate":"1917-05-29T15:18:49"} |
レスポンス本文のdataは常に null です。
レスポンス全体は、レスポンスの共通形式を参照してください。
{"success":true,"data":null} |
{name}で指定された人物の情報を削除します。
一部の人物は保護されており削除できません。
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エンコードして指定してください。
※ただし、ブラウザーやプログラミングのライブラリーにはこの変換を自動的に行ってくれるものもがあるので、使用するときに意識しなくて良いかもしれません。
DELETE
(このAPIにはリクエスト本文はありません。)
(このAPIにはリクエスト本文はありません。)
レスポンス本文のdataは常に null です。
レスポンス全体は、レスポンスの共通形式を参照してください。
{"success":true,"data":null} |
すべての登録内容を初期状態に戻します。
https://umayadia-apisample.azurewebsites.net/api/persons/all/reset
DELETE
(このAPIにはリクエスト本文はありません。)
(このAPIにはリクエスト本文はありません。)
レスポンス本文のdataは常に null です。
レスポンス全体は、レスポンスの共通形式を参照してください。
{"success":true,"data":null} |
APIの一覧を取得します。
https://umayadia-apisample.azurewebsites.net/api/persons
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に対して有効なメソッドの一覧を取得します。"]} |
人物情報を表します。
項目 | 型 | 説明 |
---|---|---|
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"} |