【学習記録】REST APIを学習する前に必要な関連用語をまとめてみた。

# 目次
[1.はじめに](#1-はじめに)
[2.概要](#2-概要)
[3.関連用語](#3-関連用語)
[4.おわりに](#4-おわりに)
[5.参考](#5-参考)


# はじめに
:::note warn
こちらは、個人の学習記事になります。以下の点をご承知おき下さい。
- 学習中の内容になります。必要に応じて都度加筆・修正致します。
- 出来る限り正しく記載するよう努力致しますが、間違い、ミスも御座います。コメントにてご指摘、アドバイス頂けたら幸いです。
- <b>二次情報としての使用は推奨致しません。</b>ご了承ください。
:::

# 概要
「REST API」について学習していく上で、必要な関連用語をまとめました。超初心者が腑に落ちる様に言い回しを工夫しました。
# 関連用語

<details><summary><b>REST APIとは？？</b></summary>

そもそもコレ何だよ？って話です。まずは「REST」と「API」に分けて考えます。
- <b>REST</b>とは、「**RE**presentational **S**tate **T**ransfer」の略でWebシステムの設計方式のことを指す。「**具体的に状態を定義した情報のやり取り**」的な意味合い。
RESTには「RESTの４原則」というものがあり、これを満たしたものをRESTfulという。基本的にこの4原則を満たしていないものはRESTとは言えない。
そして4つの中で一番大事なのが「ステートレス性」。そのほかの３つ「統一インターフェース」「アドレス可能性」「接続性」について、Web開発に於いては、IDEやフレームワークが勝手に保証してくれるからあまり意識しなくてもいいとのこと。(あくまで開発だけだった場合の話)
ステートレス - 状態管理を行わない。やりとりが一回ごとに完結する。ということ。同じ情報を保持しておかないという感じ？まだ理解しきれない概念。

- <b>API</b>とは「Apprication Programing Interface」。プログラムとアプリのインターフェイス。窓口みたいなもの。Googleアカウントでログインするアプリケーションとか、PayPalで決済出来ちゃうファッションサイトとか、ああいうのもAPIが利用できるお陰という事です。多分。


 以上の二つを合体させると<b>「RESTfulな感じで作られたAPI」</b>という事。

因みに、RESTは標準化された仕組みではなくて、あくまでも「Web通信のやり取りにはこんな運用方法で作ってみよう」的な設計思想である。


理解するのに頭の中で境界が分けづらくて難しい概念や。

</details>

<details><summary><b>クエリ文字とは？(クエリパラメータ、URLパラメータ)</b></summary>

クエリパラメータとURLパラメータをカッコでこの項目にしたのには理由があります。
情報にバラつきがあり、案外境界が不明瞭だと感じたからです。それは後述します。

- <b>クエリ文字</b>
クエリー「Query」は日本語で「問い合わせ」のこと。今後、SQLがこの辺に関わってくるっぽい。クエリ文字、というか「クエリ文字列」という表現が正しい。URLの末尾に「？＝」をつけて以降サーバーに送る情報を付け足したもの。
```java
<!-- gotopoyoと検索してほしい意味 -->
<!-- ?q=gotopoyoがクエリパラメータ -->
https://www.google.com/search?q=gotopoyo
```
- <b>クエリ文字列とクエリパラメータ、URLパラメータの違い</b>

調べたが、そこそこで意味合いが違うので、厳密に分かれていない。

「？」の後に付ける情報、キーとバリュー(値)のことをそれぞれクエリキーとクエリバリューとか言ったりする。　　

例：上記でいう「？」の後の「q」と「＝」で結んだ「gotopoyo」のこと。

「？」以降の情報を付与した文字列をまとめてクエリ文字列とかクエリパラメーターだという。

URLパラメーターはクエリパラメーターと同義。

</details>

<details><summary><b>パスパラメータ</b></summary>

早速引用になりますが[パスパラメータとクエリパラメータの違い](https://zenn.dev/eri_agri/articles/859a3362db8386)

>Web通信技術におけるパスパラメーターは、REST APIにおいてURLの一部として指定される変数のことです。URLは、Webサーバー上のリソース（データや機能）にアクセスするためのアドレスのようなものです。パスパラメーターは、そのURLの中で特定の値を指定するために使用されます。
例を挙げると、以下のようなURLがあるとします：

```xml
<https://example.com/users/{user_id}>
```
>上記のURLでは、`{user_id}`という部分がパスパラメーターです。この部分は実際のユーザーのIDに置き換えることができます。たとえば、`https://example.com/users/123`というURLでは、`{user_id}`が`123`に置き換えられています。
パスパラメーターを使用することで、特定のリソースやデータに対して操作や取得を行う際に、動的に異なる値を指定することができます。たとえば、上記の例では、異なるユーザーの情報を取得するために、異なるユーザーIDをパスパラメーターとして指定することができます。
クエリパラメーターとの違いは、パスパラメーターがURLの一部として直接指定される点です。一方、クエリパラメーターはURLの末尾に`?`を使って指定され、`key=value`の形式で追加情報を渡すことができます。
パスパラメーターは、REST APIにおいて特定のリソースに対して操作を行うための柔軟性と拡張性を提供します。また、URLの構造から意味を読み取ることができるため、直感的に理解しやすくなります。
以上が、Web通信技術におけるパスパラメーターの基本的な説明です。

前項にて、クエリパラメータの説明は理解したが、パスパラメーターはURLの一部で、特定のものを表示する役割。一方、クエリパラメーターは、特定もの、表示する画面などの条件を加える役割。似てるけど、若干違う。

実は、講師の方にSpringBootについて質問した時、これに関連する内容を聞いていたので「アレのこと？？」と勝手に納得したので、その内容も以下にまとめました。

>Q: ここの部分をなんて呼ぶのが正しいのかわからなかったです。「URLパス」でいいのでしょうか？
>A:パス、でよいです。キーワードとしては**REST API URL設計**で調べるとよいです！
※私の[GitHubリポジトリ](https://github.com/gotokaka/RaiseTechTask6/pull/1)でのコードで@GetMapping`("/nowTime")` の`("/nowTime")` についての質問。

これか！！！！SpringにおいてGetMappingアノテーションで指定していたこれがパスパラメータといことだろう。呼び方は単に「パス」で良い。

</details>

<details><summary><b>HTTPメソッド</b></summary>

HTTPメソッドとは、対象のリソースに何をしたいのか指示する内容を定義したもの。以下のものがHTTPメソッドで、それぞれのの指示内容は以下の通り。

・GET-リソースの情報を取得する。
・POST-リソースに新しいを情報を与える。
・PATCH-リソースの情報を部分的に変更する。
・DELETE-指定したリソースを削除する。
その他にも様々なHTTPメソッドがある。割愛。

</details>

<details><summary><b>HTTPメッセージ</b></summary>

HTTPメッセージには、HTTP通信でのやり取りの際の情報が記載されている。記載される内容によって、どこに書かれるか決まったりしている。

- HTTPリクエスト
  記載順に並んでいる。
  <font color="Red">リクエストライン</font> - リクエストの一番最初の行に記載される。`HTTPメソッド/リクエスト対象(主にURL)/HTTPのバージョン`　で記載される。
    
   <font color="blue">リクエストヘッダ</font> - クライアント側へ送る付加情報を記載している。基本構造は名前：値の書式になっている。
    
   <font color="green">リクエストライン</font> - 本質的な情報が入るが、入らないこともある。

- HTTPレスポンス
    
    記載順。というわけでもないようです。[MDNのDocs](https://developer.mozilla.org/ja/docs/Web/HTTP/Messages)を確認した感じではそのような図で示されていました。
    
    <font color="Red">ステータスライン(ステータス行)</font>-レスポンスの一番最初の行に記載。`プロトコルのバージョン/ステータスコード/ステータステキスト(文字列)` の順に記載。ステータスコードは後述。
    
    <font color="blue">レスポンスヘッダ</font> - 返ってきた情報がどのようなものなのかを示す。基本構造はコロン（`;`）で区切られているのはリクエストヘッダと同様。
    
    <font color="green">レスポンスボディ(本文)</font> - これに本質的な情報が記載される。返ってきたステータスコードによって記載されない場合もある。





</details>

<details><summary><b>HTTPステータスコード(番台)</b></summary>

- HTTPステータスコード - HTTPリクエストに対して返ってくる処理結果。番台で意味が変わってくる。


|  番台| 意味 |
|:---:|:---:|
|100(100-199)   |情報レスポンス   |
|200(200-299)   |成功レスポンス   |
|300(300-399)   |リダイレクトメッセージ   |
|400(400-499)   |クライアントエラーメッセージ   |
|500(500-599)   |サーバーエラーメッセージ   |

めっちゃ沢山あるので参考リンクに記載します。

[参考リンク１](https://developer.mozilla.org/ja/docs/Web/HTTP/Status)
[参考リンク２](https://medium-company.com/http%E3%82%B9%E3%83%86%E3%83%BC%E3%82%BF%E3%82%B9%E3%82%B3%E3%83%BC%E3%83%89/)


</details>


<details><summary><b>通信フォーマット(データ形式)について</b></summary>

通信は、内容の構造を定義しなければやりとりができないので、決められたフォーマットを使って通信をする。主流が以下二つ。テキスト形式でやりとりする。

- JSON-「JavaScript Object Notation」の略。人間が読める(読みやすい)、軽量、コーディングが少なく、処理が高速。記述に一定の取り決めがある。　[リンク](https://www.oracle.com/jp/database/what-is-json/)
- XML-HTMLと同様のマークアップ言語。HTMLに似たタグを使った記述方法をとる。JSON形式より自由度が高く、情報を詰め込める。　[リンク](https://docs.oracle.com/cd/E19227-01/821-0424/6nlfr1bur/index.html)

</details>


# おわりに

今回は、REST APIを学習する上で必要な基礎中の基礎の用語を学習しました。
この基本知識を元に、これから「Postman」ツールを使ったりする訳ですが、それはまた別でまとめてみます。
他にも、学習の道すがら出会った何だソレ概念や用語もあったのですが、それもまた後日で。
ありがとうございました！

# 参考
REST APIについて
- https://tech.012grp.co.jp/entry/rest_api_basics
- https://learn.microsoft.com/ja-jp/azure/architecture/best-practices/api-design
- https://developer.mozilla.org/ja/docs/Glossary/REST

クエリ文字、クエリパラメータについて
- https://www.itnavi.jp/words/%E3%82%AF%E3%82%A8%E3%83%AA%E6%96%87%E5%AD%97%E5%88%97/
- https://be-marke.jp/articles/knowhow-queryparameter
- https://wa3.i-3-i.info/word11290.html

パスパラメータについて
- https://zenn.dev/eri_agri/articles/859a3362db8386

HTTPメソッド関連
- https://developer.mozilla.org/ja/docs/Web/HTTP/Methods
- https://diveintocode.jp/blogs/Technology/depUrlHttpMethod#:~:text=HTTP%E3%83%A1%E3%82%BD%E3%83%83%E3%83%89%E3%81%AF%E3%80%81%E5%AF%BE%E8%B1%A1%E3%81%A8,%E3%81%AE2%E7%A8%AE%E9%A1%9E%E3%81%A7%E3%81%82%E3%82%8B%E3%80%82
- https://developer.mozilla.org/ja/docs/Web/HTTP/Messages
- https://shukapin.com/infographicIT/http
- https://qiita.com/c-shiraga/items/d45338a8c1ba6d0bada4
- https://developer.mozilla.org/ja/docs/Web/HTTP/Status
- https://medium-company.com/http%E3%82%B9%E3%83%86%E3%83%BC%E3%82%BF%E3%82%B9%E3%82%B3%E3%83%BC%E3%83%89/

通信フォーマット(JSON,XML)
- https://products.sint.co.jp/topsic/blog/json
- https://www.w2solution.co.jp/corporate/tech/xml-vs-json/#:~:text=%E3%83%BBJSON%E3%81%AF%E3%83%95%E3%82%A9%E3%83%BC%E3%83%9E%E3%83%83%E3%83%88%E3%81%8C%E3%82%B7%E3%83%B3%E3%83%97%E3%83%AB,%E3%81%A6%E6%9F%94%E8%BB%9F%E3%81%AB%E8%A8%98%E8%BF%B0%E3%81%A7%E3%81%8D%E3%82%8B%E3%80%82