APIって何？ 初心者向けに完全解説

いただいた質問と解説をすべて盛り込みました

Q

エンドポイントとは？

APIにおける「窓口」のことです。ソフトウェアやサービスが外部と通信するための具体的な接続先（URL）を指します。

Q

APIの業界標準のフォーマットって例えばどんなの？

現在、Web APIの業界標準として最も広く使われているのが REST (Representational State Transfer) という設計思想です。

Q

RESTful APIとは？

RESTの原則に従って設計されたAPIのことです。以下の様な特徴を持っています。

  • アドレス可能性: 全ての情報は一意なURL（エンドポイント）で示される。
  • ステートレス: サーバーはクライアントの状態を保存しない。各リクエストは完結している。
  • 統一インターフェース: HTTPメソッド（GET, POSTなど）を使って操作を表現する。
Q

OASの記法について具体的に例を教えて

OAS (OpenAPI Specification) は、RESTful APIの仕様を記述するための標準的なフォーマットです。 

paths:
  /v1/posts:
    get:
      summary: "ブログ投稿のリストを取得します"
      # ...詳細な定義が続く

Q. これが、サーバー側で用意されているAPIの記述ということ？

はい、その通りです。これはサーバーが「/v1/posts というエンドポイントに GET リクエストを送ると、ブログ投稿のリストをJSON形式で返しますよ」と定義している設計図のようなものです。

Q. この場合、例えばユーザーはどのようなリクエストを送りますか？

上記のOASの定義に対して、クライアント（ユーザー）は以下のようなリクエストを送ります。

  • メソッド: GET
  • エンドポイント(URL): https://api.blog.com/v1/posts
Q

OAS以外の標準フォーマットは？

OAS (Swagger) が最も普及していますが、目的や思想の異なる重要なフォーマットとして **RAML** と **API Blueprint** も存在します。

RAML (RESTful API Modeling Language)

**再利用性**と**一貫性**を重視したYAML形式の言語。大規模で一貫したAPI群を効率的に設計することを目指します。

API Blueprint

**シンプルさ**と**ドキュメントとしての分かりやすさ**を重視したMarkdown形式の言語。チームでのコラボレーションを促進します。

フォーマット 構文 主な思想・特徴
OAS (Swagger)YAML / JSON業界標準。豊富なツール群。
RAMLYAML設計の再利用性、一貫性重視。
API BlueprintMarkdownシンプルさ、コラボレーション重視。
Q

getとかpostってcurlじゃないと指定できない？ブラウザで直接エンドポイントを叩くと結果が返ってくるのは、どう理解したらよい？

解説：その通りです。ブラウザのアドレスバーへの入力は、基本的にGETリクエストになります。

これは、ブラウザがウェブページを表示するために「このURLにあるデータを取得して」とサーバーに伝える操作だからです。

1. ブラウザのGETリクエストの仕組み

ブラウザのアドレスバーに https://api.blog.com/v1/posts と入力してアクセスすると、ブラウザは自動的に GET /v1/posts というリクエストをサーバーに送ります。サーバーはそれに応答して、投稿のリストのJSONデータを返します。ブラウザは、そのJSONをそのまま画面に表示します。

2. POSTなどのリクエストを送る方法

一方、POST, PUT, DELETE といったデータを作成、更新、削除するためのリクエストは、ブラウザのアドレスバーからは送ることができません。これらの操作は通常、以下の方法で行われます。

  • HTMLフォーム: ウェブサイト上のフォームでユーザーがデータを入力し、「送信」ボタンを押すと、POSTリクエストが送られます。
  • JavaScript (Fetch API, XMLHttpRequest): ウェブアプリケーションの内部で、JavaScriptのコードを使ってプログラム的にHTTPリクエストを送信します。
  • 専用ツール: Postman、Insomnia、またはコマンドラインツール（curl）など、APIテストのために設計されたツールを使います。これらのツールは、HTTPメソッドやリクエストボディを自由に指定できます。

結論

したがって、ブラウザで直接エンドポイントを叩いて結果が返ってくるのは、そのAPIがGETリクエストに対応しており、ブラウザがそのリクエストを自動的に送っているためだと理解してください。これは、APIがデータを「読み取り」可能であることを示しています。