[WIP]【社内向け】curlコマンドの作り方 初級編

curlコマンドとは

client for URL の略で、
様々なプロトコル（通信手順）を用いてURLで示されるネットワーク上の場所との間でデータの送受信を行うものです。

一番短い例で言えば
curl http://localhost:8080/
コマンドプロンプト上で、 http://localhost:8080/ の内容を取得して表示しています。
この際、APIの実装が以下であれば、

// serverは kotlin で実装。
// routing はURLを決める親となるもの
routing {
    // ローカルで動かす際は http://localhost:8080 までが親で、
    // URL の後ろに付く文字列が / と言うことになる
    route("/") {
        // httpメソッドの指定。同じURLでもhttpメソッド毎に別々に扱える
        get {
            // プレーンテキストで HELLO WORLD! と表示する
            call.respondText("HELLO WORLD!", contentType = ContentType.Text.Plain)
        }
    }
}

% curl http://localhost:8080/               
HELLO WORLD!

のように、 HELLO WORLD! の文字列が返されます。

さて、ではcurlコマンドの内容を見ていきましょう。
基本的な構成は curl [options] [URL] のようになっていて、
一切 options を付与しないのが上の状態。

そして今回のTODOアプリで使用するのは以下の4通り

TODO一覧取得API

curl -X GET http://localhost:8080/todos

TODO登録API

curl -X POST http://localhost:8080/todos \
-H "Content-Type: application/json" \
-d '{ "title": "タイトル", "detail": "内容", "date": "2022-12-21" }'

TODO更新API

curl -X PUT http://localhost:8080/todos/1 \
-H "Content-Type: application/json" \
-d '{ "title": "更新後のタイトル", "detail": "更新後の内容", "date": "2023-12-12" }'

TODO削除API

curl -X DELETE http://localhost:8080/todos/1

URL に関して

http://localhost:8080

ローカルで起動させているとこのようになります。 8080 はポート番号です。
一般的なURLで言うと https://qiita.com のような箇所ですね。

/todos

例で route("/") と書いていた箇所が route("/todos") と言う指定になっています。
TODOに関するAPIなのでこのような指定となり、ユーザーに関するAPIであれば /users などが一般的でしょう。

/1

PUT や DELETE にのみ存在するこの値ですが、 API仕様書で言う /:id のことです。
更新・削除対象となる TODO の ID番号 を入れています。
APIの内部処理として、該当IDのレコードをDBから取得しますが、
そのレコードに対して操作することを示しています。

options に関して

-X

これはHTTPメソッドの指定。
代表的なものが今回使用している GET/POST/PUT/DELETE 辺りです。
API仕様書にある通りのものを付与してあげましょう。
なお、特に付与しない場合のデフォルト値は GET になります。

-H

これはヘッダーですね。リクエストの中身には ヘッダー と ボディ が存在します。
リクエストヘッダー や HTTPヘッダー などで検索すれば詳細内容はわかるかと思います。
今回必要なのは Content-Type で、リクエストボディ の内容がどのような形式で送られてくるのかを明記しています。
API仕様書に書いてある通り JSON形式なので、 application/json です。
参考 HTTPヘッダ一覧: http://www.cresc.co.jp/tech/java/Servlet_Tutorial/Att_03.htm

-d

こちらは先ほども名前が出ましたが、リクエストボディの中身です。
主に POST や PUT で、serverに送りたいデータを書いていきます。
こちらも仕様書に沿った内容ですが、ヘッダーで指定したようにjson形式で書きましょう。
見やすく改行すると以下のようになります

{ 
  "title": "タイトル",
  "detail": "内容",
  "date": "2021-12-12" 
}

まずはここまで。
今後追記・修正していきます。