FastAPI 超初心者向け入門 / 準備編

そんちゃー君

2022年12月3日 13:53

※こちらはHTTPやAPIと言う用語の解説をする準備編です。
しっとるわい！という方は読み飛ばして次の本編へお進みください。

API専用の最速フレームワークの１つとして有名な Python製 FastAPIが最高だったので、もっと広まって欲しい！とチュートリアルを書いておくことにしました。

目標

チュートリアル終了時のゴールは以下です。

1. API触ったことがある人になる
2. HTTPの実物体験のある人になる
3. Python の仮想環境つくった事ある人になる
4. FastAPIで要約（サマライズ）のAPIサーバーを完成

この記事の対象者

APIってなんなん？、でも仕事でよく聞くしなぁ、という方
HTTPとかいまいちわかって無くて不安、という方
本家チュートリアルを独習するのは大変、という方

にお役に立てるように書きました。
Pythonはざっくり、、で十分出来る内容です。　覚えてない書き方が調べやすいチートシートはこちらにあります。。

ガッツと時間がある方はこちらで。日本語版は不完全なので英語版をおすすめします。
[本家チュートリアル]（https://fastapi.tiangolo.com/tutorial/first-steps/）

英語ですがこちらUser Guideは非常にわかりやすく、仕事で使うのであればいずれにしても後で全体に目を通すのをおすすめします。

なおFastAPIはPythonフレームワークですが、Pythonの解説は世にたくさんあるので割愛させていただきます。

(Pythonのやる気が出る記事：20+ Best Python Project Ideas ) [https://unstop.com/blog/python-projects-ideas]
Pythonは学習しやすい言語ですのでおすすめです！

挫折しないために

コンピュータとかネットワーク関係の話をしている時に、険悪だったり意地悪な印象を受けたことはないでしょうか。
おそらく理由は大きく２つ、「心配になる」「イライラしてしまう」かと思います。

サーバーで費用がかかったり、課金サービスをしていると売上に影響したり、セキュリティーの不安があったり「心配」なことが何かと多いサーバー関連。
また、そうでなくても複雑・専門用語が多いコンピューターの話に「サーバー側」「クライアント側」の２要素があり、言葉で表現が面倒であったり頭を使うため余計に「イライラする」しそうです。

記事を見ていただき、チュートリアルをする中で記述に不備があったり、作業がうまく行かず「む」っとなることも出てくるかもしれないです。コンピューターは便利に、人の労働を助けるためのもので、気分が良くなるために使うのがゴールです。
どうかイライラせずに、焦らず読み進めていただきたいと思います。
また、不備があるときには遠慮なくメッセージなどをいただければ幸甚です。

記事ではFastAPIに入門で知っていると捗る、理解しやすくなる為の「こまかい」違いを必要に応じて説明をしています。
しかし、細かい違いを説明するのはあくまでもFastAPIを楽に習得するためです。

コンピューティング、特にネットワーク関連のことになると些細な事、解釈の違いや用語の定義について「それは違う！」と減点しに来る話が出がちですが、初心者が入門する時に、そういう減点主義は害しかありません。
Web技術の活用のため楽しく習得するきっかけとして、あまり細かいことは気にしすぎないよう、楽しめる範囲で入門していただけたらと思います。

この記事のざっくり

FastAPIについて説明する前に、FastAPIが書かれている言語 Pythonのセットアップと、APIについてざっくり解説。

以下の３つについてざっくり解説します。

APIってなに？
HTTPについて
~~Python 環境の作り方 (pyenv, venv ) 　※長くなったので次回記事にしました~~

「いらんて！」という方は飛ばして本編記事にお進みください。

用語

以下の用語が出てきます。

サーバー / ホスト
クライアント
クラウド
HTTP , HTTP Request / Response
ブラウザ
サーバー
バックエンド / フロントエンド
API
method
header / body

使っていたり、聞いたことがある言葉も多いと思います。
厳密に全て知っている人は稀ですので、わからなくてもOK。目を慣らして見たことある状態になれれば大丈夫です。

HTTPこの記事のメインの単語でブラウザが使う通信方法（ルール）のことです。他は記事を参考においおい理解を進めてください。

1. APIってなんですか

FastAPIはAPI専用フレームワークですが、このAPIは正式にはWeb APIのことで、Application Programming Interface for Web の略です。　
この「Web」は web server and web browser、インターネットを利用する時に使うブラウザとブラウザにデータを提供するサーバーをつなぐ仕組みの１つです。　

って言われてもピントキませんよね？
例えばこれは form 送信するときの例です。こんなのを送信・受信するのがWebAPIです。

POST /test/post HTTP/1.1     
Host: reqbin.com               
Accept: application/json
application/x-www-form-urlencoded
Content-Length: 6
                                  
q=test

メモ帳とかで掛けるテキストの普通の文字です。

で、APIってなんですか？？

APIという言葉はもともとはCなどシステムプログラミングなどで使われていた用語で、システムライブラリなどの機能をプログラマが利用する時に使うインターフェイス（関数サービスなど）をAPIと呼んでいたのが始まりです。
インターネット普及以前は通信が介在していない、コンピュータの中のプログラム間のインターフェイスが一般的だった頃にできた用語です。

正式な名称はWeb APIのはずですが、実際に利用する人・開発する人の人口が極端に増えたため、現在ではAPIと言えばブラウザ通信（HTTP）のAPIを指すことが圧倒的に多く、FastAPIもそのまま「高速なAPI」という名前にしたのでしょう。
この記事でも、ここから先はAPIと省略して使います。

Web APIは通信（HTTP）のこと

はじめに紹介したAPIで送るテキストを送るためにHTTPという通信フォーマットを使います。 Web APIとはHTTP通信するプログラム（サービス）のことです。

会話などでAPIが誰なのか??と、分かりづらい印象になるのは APIの機能(ソフト）の話なのか、ハード（物）の話なのか、物ならそれはどこにあって何なのか？いまいちピンとこないからではないでしょうか。

アプリやWeb開発の現場などで、APIと言ったときには、

- APIサーバーが提供するサービス、利用するブラウザ側の通信の両方
- HTTP通信で実現するよ、APIサーバーが機能を提供するよ
- ブラウザやアプリから通信してデータベースから読んだり書いたりするよ

という場合がほとんどかと思います。

１，２，３セットでAPIとして機能します。この記事では基盤となる２の知識を主に。

図にするとこんな。色んな要素がありますけど、会話では全部毎回説明していられないので「APIで〜」ってなるので、混乱しやすいところです。
APIと言われたら、「データ通信」して「データをもらったり」「サーバーにわたしたり」する、と理解していただければと思います。

（ざっくりまとめると）
Web API …. ブラウザやスマホとサーバーの為のデータ通信や、その機能を提供するソフト
APIサーバー …. WebAPIを実現するソフトやデータベースなどが動くサーバー(パソコン）
API 　　　… コンピュータどうして何かの機能を提供するためのインターフェイス（接続手段）

難しそうな名前でも気にしないでください

Web系の技術の勉強がややこしい、難しく感じるのは「ビジネスの都合」でルールや用語を場当たり的にたくさん作ってしまったことも、大きな理由になっているように思います。Web系は進歩が早く、アメリカの大企業が勝手に決めて配布したために、仕様や名称には常に混乱があり、今も続いています。

始めて学ぶ方は用語を知らなくても気にせず、「またすごそうな名前を付けたね」くらいで楽しんでいただければ,と思います。

2. HTTPについて

APIというのは商品名のようなもので、実態はHTTP通信です。
HTTPの基本知識をスルーして、見様見真似でなんとなくAPIのプログラムをすることも出来るのですが、事あるごとに不明な用語が出てきてモヤモヤするので楽しくないと思います。

FastAPIのコードの中もHTTPの用語が出てきます。HTTP通信をするためのフレームワークなので当たり前ですが、bodyのように一般的に使う単語もあるので「HTTPの仕様でいうOOOなんだな」とわかると楽です。

HTTPは文字列通信

まずは現物を見てみましょう。以下はAPIで使うHTTP通信の実際のデータで、リクエスト（ブラウザがサーバーへ送信）する時のデータ例です。

POST /echo/post/json HTTP/1.1     <--- POST 、URL,  HTTP version
Host: reqbin.com                  <--- ヘッダー始まり
Accept: application/json
Content-Type: application/json     <--- jsonを指定
Content-Length: 81
                                   <--- 空行(改行のみ）この下はBody
{
  "Id": 78912,
  "Customer": "Jason Sweet",
  "Quantity": 1,
  "Price": 18.00
} page:0, limit:50

１行目がリクエスライン
２〜５行がheader,
１行空白を入れて
その下がbody

図にするとこんな。実は最初のリクエスト行だけでも送れる単純なものです。

リクエストをすると、サーバーは返答（レスポンス）を返します。
こちらもステータスライン、ヘッダ、ボディ　の３部構成の同じフォーマットです。

method (メソッド）

HTTPリクエストの１行目は

POST /echo/post/json HTTP/1.1     <--- POST 、URL,  HTTP version

となっていて、一番最初のPOSTの部分は送信タイプでmethodという名称です。

methodは８種類ありますがFastAPIでは以下の４つを使います。

GET
PUT
POST
DELETE

データをもらったり送ったりする用途の指定を明示するもので、

- データをもらいたいときには GET,
- 新しく追加するときにはPOST,
- (既存データへの）アップデートはPUT,
- データの削除はDELETE

です。

RESTについて

このmethod を無視してAPIを作ることも可能で、以前はそうしたAPIも数多くデザインされていました。
しかし、開発の規模・人数が多くなったり、OPENなAPIとして外部へ公開することが増え,現在ではmethodに準拠したデザインをするのが一般的で,これをREST APIと呼びます。　(RESTful API とも呼ばれます）

(What is REST)[https://restfulapi.net/]

REST is an acronym for REpresentational State Transfer and an architectural style for distributed hypermedia systems. Roy Fielding first present

厳密には methodを使う以外のルールが細々ありますが、会話の中でRESTと言われたら、まずは methodの定義従ってAPIをデザインする、と考えるとわかりやすいです。

リクエストのパラメータ３つ

リクエストをサーバーへ送信する時に、特定のデータを問い合わせたり、なにか検索のをしたいときなど、いくつかの「変数」を送信したくなりますが、これをパラメーターと呼びます。

https://api.real-estate.com/apartment/123456?info=all

この例では 123456 と info=all が、APIがサーバーに問い合わせるパラメータです。

リクエストでサーバーに送る方法（種類）は３つあります。

Path Parameters (パス・パラメータ）
Query Parameters (クエリ・パラメータ）
Request Body (クエストボディ）

FastAPIではこれらを洗練された形でサポートしています。　

詳しくはこのページに詳細があります。
https://fastapi.tiangolo.com/tutorial/path-params/

1.Path Parameters

パスパラメータはURLアドレスの一部としてパラメータを渡す方法です。
リクエストされたURLから,APIサーバーが解釈して使用します。

e.g.) あるAPIで 5 を指定した場合

https://my-server.com/items/5    // 5 がパスパラメータの部分

2. Query parameters

主にGET methodで使われるパラメータで,URLの最後にパラメータを列挙します。（これをURLクエリと呼びます）
文字数は2048文字までの制限があり、大きなデータの送信はできません。

e.g.) skip=0, limit=10 という値を渡す場合

http://my-server.com/items/?skip=0&limit=10

? から後の部分がURLクエリです。
これはURLの仕様として決まっているもので、Query Stringが正式名称、 Query String Parameters とも呼ばれます。

Query という単語単体では、コンピューティングでは他の技術でも使うので,使用には注意が必要です。
(Webのフロントエンドだけの開発、それ以外の開発者と混ざっているかによります）
※他によく使われるのは Databese Query でコチラも単にQueryと単体で使われることが多いです。

what is query？
query とはもともと、お役人や組織に対する質問のことで、現代では記者会見などでの質問もqueryと呼びます。

3.Request Body

Request bodyは先に出てきた HTTPリクエストのフォーマットのbodyのことで、図の青い所にあたります。(図ではメッセージ本体となっていますが正式には body)

bodyはPUTやPOST でデータを送信する場合に使われます。
bodyとは「本文」「本体」と考えるとわかりやすいです。

webページで名前や住所を入力して送信したり、画像をアップロードするようなフォーム送信はPOSTで,bodyに入力したformの情報がはいって送信されます。

前述の パスパラメータやクエリパラメータはURLを見て確認できる形ですが、Request body は送信本体の中にデータを入れて送る方法です。
目視で確認するにはChromeブラウザであれば、マウス右クリック->検証　で出てくる開発用コンソールのネットワークから確認ができます

bodyデータは複数のフォーマットがあり,ヘッダでJSONなどフォーマットを指定して、それに合うデータを送信します。　　

Content-Type: application/json　をヘッダに指定してJSONで送信する例

{                                                                                                                        
  "name": "tiger",                                                                                                       
  "description": "tiger in the woods",                                                                                   
  "price": 5000,                                                                                                         
  "tax": 0.1                                                                                                             
}

Pythonの環境！

長くなってしまったので次の記事にします。。。。ごめんなさい

（オマケ）

複雑になるHTTPの世界
元は単純だったHTTPですが、現在は複雑化が進んでいます。
Eコマースなど商用利用の拡大と並行して、詐欺など悪用も増加し、それに対応する形で情報を暗号化する仕様の１つがJWTです。　

HTTP自体も HTTP1.1 からHTTP2,　HTTP3と多機能化することになっているので、基本を押さえておくと会議での不安が減りそうです。

次の記事：Pythonの環境設定、FastAPIチュートリアル１

いいなと思ったら応援しよう！

サポートありがとうございます😊 ベトナムにお越しの際はお声がけくださいね🌻