プログラミングを始めると必ずAPIという言葉が出てきます。今の時代、世の中には様々なAPIが公開されており、それらを上手に使うことによって、0からコードを書く必要がなく、機能を連携することができます。これだけ言ってもいまいちピンと来ないかと思いますが、APIを使えることでエンジニアとしての幅が広がりますし、確実に使えるようになる必要があります。しかし、APIを使い始めようと思って勉強をしているとエンドポイントやエントリーポイントといった言葉が出てきて、わからない方も多いかと思いますので、今回はAPIのエンドポイントとエントリーポイントとの違いについてご説明します。
APIとは
APIとは、Application Programming Interfaceの頭文字を取って付けられており、そのままの意味として“アプリケーションやソフトウェアをプログラミングするためのインターフェイス”です。インターフェイスという言葉は、接続部分のことを意味しています。簡単にいうと何か2つを繋ぐものであり、パソコンとモニターを繋ぐこともインターフェイスですし、人がウェブサイトを見ているのもユーザーインターフェイス（UI）と言ったりします。インターフェイスという言葉はそこら中に出てきますので、是非覚えましょう。
さてAPIの話に戻りますが、APIを使うことでプログラム同士の間でデータをやりとりしたり、外部の機能を付与することができたりします。
1つ例をあげると、あなたが車を作るとなったときに、0からタイヤを作ると非常に大変だと思いますが、タイヤ屋さんからタイヤを購入して車にはめたり、ハンドル屋さんからハンドルを購入してはめるなどして、部品を外部から入手することで車が簡単に作れちゃいます。このようにAPIという接続方法で、機能やデータ連携をすることがどれだけ楽で、エンジニアに取って大事なのかがわかったかと思います。
このようにあなたが普段使っているウェブサービスは実は裏側では、別のサービスとAPI連携されていて、その外部サービスからのデータを用いている場合があります。例えばあなたのサービスに天気情報を付与したいということであればGoogleで「天気予報 API」と検索することで、天気予報の情報をAPIで提供しているサイトを発見することができます。この情報を利用して、あなたのサービスに天気予報を表示させることも可能です。ちなみに私は以前、OpenWeatherのAPIを使って、Slackに「今日の天気は？」と聞くと、天気情報を教えてくれるという機能を追加したことがあります。これはわざわざ天気予報を見に行かなくてもいいので良かったですね。
このようにAPIは、アイディアによって使い道は無限大にありますし、無限の可能性を秘めています。
APIエンドポイントとは
エンドポイントとは、特定のリソースに対して与えられた固有の一意なURIです。
URIとは
Uniform Resource Locatorの頭文字でURL（Web上の住所）とURN（Web上の名前）で構成されており、2つの総称だと思ってください。
これだけだと非エンジニアの人には理解ができないですよね・・・。
簡単に言うと、「エンドポイント＝接続先」のことです。
先ほど、APIは外部サービスやデータを連携することと説明しましたが、連携するには接続する場所があって、それがURIです。
例えば、国産チャットツールであるchatworkのAPIエンドポイントのベースとなるURIは「https://api.chatwork.com/v2」となっています。つまり、このhttps://api.chatwork.com/v2にアクセスすることでAPIを使って、連携することができるため、エンドポイント＝API連携するためのURIと覚えてください。
APIエンドポイントのURI設計の注意点
APIエンドポイントは、APIにアクセスするためのURIを指していると伝えましたが、そのURIは非常に大事です。そのためURIの設計をする上で注意点を説明していきます。
URIは短く、エンジニアが使いやすくする
URIはエンドポイントであり、リソースを指しているのですが、URIは短く、わかりやすく、入力の間違いがないように設計を意識してください。
例えば、先ほどのchatworkのURIであるhttps://api.chatwork.com/v2を元に見てみましょう。
このURIは、非常に短くなっていますし、apiやchatworkという単語が入っていて、ひと目見ただけでわかりますよね。さらに/v2は、version2を表しているんだなと気づくので、バージョンが更新されるごとにv3やv4になっていくことが予想できます。
このようにURIを作った側だけがわかるものではなく、誰が見てもわかるようにすることがユーザビリティが良いエンドポイントと言えます。
URIは小文字で統一する
URIは、大文字と小文字が両方混じっていると打ち間違いによってAPI連携でエラーが起こる場合もあるため、なるべく小文字のみに統一することをオススメします。大文字に統一してもいいですが、大文字を打つのが手間になってしまうため、小文字の方が好ましいです。
適切なHTTPメソッドを使用しているか
HTTPメソッドとは、「クライアントがサーバーに命令を出すための方法」です。
クライアント＝ウェブブラウザ（Google Chrome、Safariなど）、サーバー＝情報が入っている箱と考えてください。
つまりあなたが現在見ているこの記事ですが、あなたが使用しているブラウザが、私のレンタルサーバーにページ情報をくださいといった命令を出して、受け取っていることで見れています。この命令のことをリクエストと言ったりしますが、そのリクエストの種類に応じてHTTPメソッドの種類が以下のように変わります。
| HTTPメソッド | 意味 | 使用場面例 |
|---|---|---|
| GET | 何かしらのデータを取得する時に利用 | ウェブページ情報、画像データ、API経由でのデータなど |
| POST | クライアントからサーバーにデータを新規送信 | Webページ情のフォームからデータを送信、ブログで新記事を投稿など |
| PUT | POSTと同じデータの送信だが、既存データの更新で使われる | 既存アカウントの情報を更新、SNSの投稿の編集など |
| DELETE | 既存データを削除する時 | アカウントのデータ削除、ブログ記事の削除など |
| PATCH | データの一部変更 | 既存アカウントの一部データ更新、SNS投稿の一部編集など |
POSTとPUTの違い
POSTとPUTは、両方ともデータ送信でしたが、POSTは新規データを送信する場合に使われて、PUTは既存データの上書き更新をする際のデータ送信に使われます。
またURIの指定方法が違ってきます。
POST /image とした場合、サーバー側で割り振られてGET /image/1111 のような新しいURIがアクセスできるようになります、しかしPUTは、PUT /image/1111のように使用者がリソースを指定する場合に使われます。
PUTとPATCHの違い
PUTは完全に既存データを上書きしたい場合に使いますが、PATCHは、データの一部だけを上書き更新する場合に使われます。
APIエンドポイントとエントリーポイントの違いは？
エンドポイントについては理解していただいたと思いますが、APIを学んでいると”エントリーポイント”という言葉が出てきます。私はエントリーポイントを調べた所、「プログラムを実行するうえで、プログラムやサブルーチンの実行を開始する場所のこと」と説明をされましたが、全くわかりませんでした。
しかし実際は、もっとすごく単純でエンドポイントと意味は同じです。見ている視点が違うだけで言葉が変わっているだけです。
API連携したい側から見た場合のULIは、エンドポイントと言いますが、APIでデータを提供する側から見たULIがエントリーポイントになるだけです。
先ほどのあなたのサービスに天気予報の情報を追加したい場合は、天気予報APIを使ってデータをGETするのですが、そのGETする側ではエンドポイントで、POSTする側がエントリーポイントになります。
でもなんで「エントリー」や「エンド」という言葉が使われるか疑問ですよね・・・。エントリーは入り口の意味で、エンドは出口と考えるととても簡単で、処理が始まる場所と終わる場所ということです。
まとめ
APIのエンドポイントについてわかりやすく説明したつもりですが、ご理解いただけましたでしょうか。また、エンドポイントだけではなく、エントリーポイントという言葉も耳にしますが、実際は使う側と提供する側の視点の違いで言葉が変わっているだけで、実際の意味は同じでした。このようなIT用語は非常に紛らわしくて難しい説明が多いですが、実際に理解してしまうと簡単なことがほとんどです。今回はエンドポイントとエントリーポイントについて理解いただければ問題ないので、APIを利用してサービスやアプリケーションの拡張に挑戦してみてください。
コメント