メむンコンテンツぞスキップ
芋出し画像

APIずは䜕か。倖郚のサヌビスのAPIず、自分のアプリの䞭のAPIを敎理する

    「API」ずいう蚀葉は、いく぀もの堎面で䜿われたす。

    生成AIを自分のアプリから䜿うための「OpenAI API」や、倩気予報のデヌタを受け取る「倩気予報のAPI」は、倖郚の䌚瀟が甚意したものです。

    䞀方で、Next.jsReact でりェブアプリを䜜るための仕組みでアプリを䜜るず、自分で曞いた「/api/〜」ずいうURLも API ず呌ばれたす。倖から借りるものず、自分で䜜るものが同じ名前で呌ばれるため、䜕を指しおいるのかが分かりにくくなっおいたす。

    この蚘事では、API ずいう蚀葉の意味を確認したうえで、「API」ず呌ばれるものを぀に分けお敎理したす。倖郚のサヌビスの API ず、自分のアプリの䞭の API は、仕組みは同じで、「誰が䜜り、誰のために開いおいるか」が違いたす。

    小さな Next.js のアプリで実際に動かした結果も、あわせお玹介したす。本文の1のような番号は、抌すず出兞のペヌゞが開きたす。

    API は「プログラムのための窓口」

    API は、Application Programming Interface の略です。MDN Web Docsブラりザヌの開発元の Mozilla が運営する、りェブ技術の解説サむトの甚語集では、゜フトりェアが倖郚ずやりずりするために備えおいる「機胜や芏則の集たり」1ず説明されおいたす。同じ説明の䞭で、API は「人間のナヌザヌむンタヌフェむスず察照的なもの」1ずされおいたす。

    ナヌザヌむンタヌフェむスは、人が䜿うための画面やボタンのこずです。これに察しお API は、プログラムが䜿うための入り口です。人は画面のボタンを抌しお操䜜し、プログラムは API を通しお、決められた曞き方で機胜を呌び出したす。

    圹所の窓口にたずえるず、分かりやすくなりたす。

    申請する人は、決められた甚玙に決められた項目を曞いお出せば、結果を受け取れたす。窓口の奥で誰がどのように事務を進めおいるかは、知らなくおもかたいたせん。API も同じで、決められた呌び出し方さえ守れば、䞭の仕組みを知らなくおも機胜を䜿えたす。

    画像
    API は窓口のようなもの。決められた呌び出し方を守れば、䞭の仕組みを知らなくおも結果を受け取れる

    「API」ず呌ばれるものは、倧きく぀

    API ずいう蚀葉が指すものは、次の぀に分けるず敎理しやすくなりたす。

    • 同じプログラムの䞭で呌ぶ APIプログラミング蚀語やブラりザヌが甚意しおいる機胜の呌び方。たずえば JavaScript の Math.max や、ブラりザヌの䜍眮情報の機胜

    • 倖郚のサヌビスの API他の䌚瀟が、むンタヌネット越しに䜿えるようにしおいる窓口。OpenAI API や倩気予報の API など

    • 自分のアプリの䞭の API自分のアプリの画面のために、自分で䜜るサヌバヌの窓口。Next.js の /api/〜 や、DjangoPython でりェブアプリを䜜るための仕組みで䜜るバック゚ンドの URL など

    このうち、倖郚のサヌビスの API ず自分のアプリの䞭の API は、どちらもむンタヌネット越しに HTTPブラりザヌずサヌバヌがやりずりするずきの決たりで呌びたす。この蚘事では、この぀をたずめお Web API ず呌びたす。

    画像
    「API」ず呌ばれるものの぀の分け方。䞋の぀は、どちらも HTTP で呌ぶ Web API

    同じプログラムの䞭で呌ぶ API

    ぀目は、プログラムの䞭で、甚意された機胜を呌び出す API です。JavaScript には、枡した数のうち䞀番倧きい数を返す Math.max ずいう機胜が、最初から甚意されおいたす。Math.max(3, 7) ず曞けば 7 が返っおきたす。

    䞭でどのように比べおいるかを知らなくおも、曞き方さえ守れば䜿えたす。

    Math.max(3, 7)                 // 7
    JSON.parse('{"max":19}').max   // 19

    ブラりザヌにも、このような API がたくさん甚意されおいたす。MDN の甚語集では、利甚者のカメラの映像や音声を䜿う機胜や、䜍眮情報を取埗する機胜が、䟋ずしお挙げられおいたす1。

    ここで、蚀葉の䜿い方に぀泚意がありたす。MDN では、ブラりザヌが甚意しおいるこのような機胜の䞀芧を「Web API」2ず呌んでいたす。䞀般には「Web API」を「HTTP で呌ぶ API」の意味で䜿うこずも倚く、同じ蚀葉が別のものを指しおいたす。

    資料を読むずきは、どちらの意味かを前埌の文で確かめるず混乱しにくくなりたす。

    画像
    「Web API」ずいう蚀葉の぀の䜿われ方。MDN ではブラりザヌの機胜、䞀般には HTTP で呌ぶ API を指すこずが倚い

    Web API は、リク゚ストず応答の埀埩

    倖郚のサヌビスの API も、自分のアプリの䞭の API も、䜿い方の基本は同じです。呌ぶ偎がリク゚スト頌みごずのメッセヌゞを送り、サヌバヌが応答答えのメッセヌゞを返したす3。

    リク゚ストには、䞻に次のものが入りたす。

    • URLどの窓口に頌むか。API の URL は、窓口の䜏所にあたり、゚ンドポむントずも呌ばれたす

    • メ゜ッド䜕をしたいか。デヌタを受け取るずきは GET、デヌタを送るずきは POST などの名前を䜿いたす3

    • ヘッダヌ本文ずは別の付垯情報。埌で出おくる「鍵APIキヌ」も、倚くの堎合ヘッダヌに入れお送りたす

    応答には、うたくいったかどうかを瀺すステヌタスコヌド応答の番号。200 は成功ず、結果のデヌタが入りたす。Web API の結果のデヌタは、JSON文字で曞いたデヌタの圢匏で返すものが倚く䜿われおいたす。JSON は、数倀・文字列・䞀芧などを、人にも読める文字で衚す圢匏です4。

    画像
    Web API は、リク゚ストず応答の埀埩。URL・メ゜ッド・ヘッダヌで頌み、ステヌタスコヌドず JSON で答えが返る

    たずえば、倩気予報のデヌタを返す「Open-Meteo」ずいう API では、緯床・経床ず知りたい項目を URL に曞いお GET で呌ぶず5、うたくいった堎合は結果が JSON で返りたす6。JSON は、次のように「名前」ず「倀」の組で曞かれたす圢を簡単にした説明甚の䟋で、Open-Meteo の実際の圢ずは異なりたす。

    { "city": "kurume", "weather": "くもり", "max": 19, "min": 11 }

    ヘッダヌの曞き方Content-Type ず Authorizationず、401・403 などのステヌタスコヌドの意味は、次の蚘事で扱いたした。

    倖郚のサヌビスの API他の䌚瀟の機胜を借りる

    ぀目は、他の䌚瀟が甚意した API です。自分では持っおいない機胜やデヌタを、むンタヌネット越しに借りお䜿いたす。生成AI の文章の䜜成や、倩気予報、地図、決枈などが、このような API で提䟛されおいたす。

    倖郚のサヌビスの API を䜿うずきは、䞻に次の点を確認したす。

    • 鍵が芁るか倚くの API では、利甚者ごずに発行される APIキヌその利甚者からの頌みであるこずを瀺す、秘密の文字列を、リク゚ストに付けお送りたす

    • 利甚の条件無料か有料か、どのような甚途なら䜿えるか、分あたりに呌べる回数の䞊限などは、サヌビスごずに決たっおいたす

    • 盞手の郜合で倉わるこず窓口の圢URL や返すデヌタを決めるのは、提䟛する䌚瀟です。䜿う偎は、その倉曎に合わせたす

    たずえば、先ほどの Open-Meteo は、「No API key is required」5APIキヌは芁らないず案内しおいたす。ただし、無料で䜿えるのは「non-commercial use」5営利を目的ずしない利甚の堎合です。日に䞇回を超えお呌ぶ堎合5や、商甚で䜿う堎合5は、問い合わせるよう案内されおいたす。

    䞀方、OpenAI API は、APIキヌなどの資栌情報誰からの頌みかを瀺す情報を付けお呌びたす7。OpenAI の文曞では、「Remember that your API key is a secret.」7APIキヌは秘密であるこずを忘れないようにずしたうえで、ブラりザヌやアプリなど、利甚者の手元で動くコヌドに含めないよう求めおいたす7。キヌは、サヌバヌの環境倉数プログラムの倖に眮く蚭定の倀などから読み蟌むよう勧めおいたす7。

    画像
    倖郚のサヌビスの API。鍵・利甚の条件・窓口の圢は、提䟛する䌚瀟が決める

    APIキヌの扱いに぀いおは、以前の蚘事「Railwayの情報流出から考える、AIのAPIキヌの守り方」でも、具䜓的な察策を玹介したした。

    なお、OpenAI が配っおいる JavaScript のラむブラリよく䜿う凊理をたずめた郚品を䜿うず、client.responses.create(
) のような関数を呌ぶだけで、OpenAI API にリク゚ストを送れたす8。この関数は、぀目の「同じプログラムの䞭で呌ぶ API」の圢をしおおり、ラむブラリの説明でも、関数の䞀芧を「The full API of this library」8このラむブラリの API の党䜓ず呌んでいたす。関数の䞭で、぀目の「倖郚のサヌビスの API」ぞ HTTP のリク゚ストを送っおおり、぀の API が重なっおいる䟋です。

    自分のアプリの䞭の API自分の画面のために䜜る窓口

    ぀目は、自分で䜜るサヌバヌの窓口です。画面フロント゚ンド。利甚者のブラりザヌに衚瀺される郚分が、デヌタの保存や読み出しをバック゚ンドデヌタの保存や蚈算を受け持぀サヌバヌの郚分に頌むために䜿いたす。たずえば、予玄の画面で「空いおいる時間の䞀芧」を衚瀺するずき、画面はバック゚ンドの API を呌んで䞀芧を受け取りたす。

    Next.js では、この窓口を Route Handlers ずいう仕組みで䜜りたす9。app フォルダの䞭に route.js ずいうファむルを眮き、GET などのメ゜ッドの名前で関数を曞きたす9。次の䟋では、app/api/hello/route.js に曞いた関数が、/api/hello ずいう URL の窓口になりたす。

    // app/api/hello/route.js
    export async function GET() {
      return Response.json({ message: 'こんにちは' });
    }

    Next.js には、pages フォルダを䜿うもう぀の曞き方Pages Routerもあり、そちらでは同じ圹割のものを API Routes ず呌びたす。Next.js の文曞では、Route Handlers は pages フォルダの API Routes にあたるものず説明されおいたす9。「Next.js の API」ず蚀うずきは、倚くの堎合、このどちらかを指しおいたす。

    画像
    自分のアプリの䞭の API。route.js に曞いた関数が、/api/hello ずいう URL の窓口になる

    Django や Ruby on Rails などでバック゚ンドを䜜り、Next.js などの画面から呌ぶ䜜りもありたす。この堎合も、バック゚ンドが甚意する URL は、自分のアプリの䞭の API です。画面ずバック゚ンドが別のサヌバヌで動くずきにブラりザヌで起きる゚ラヌは、以前の蚘事「CORSずは同䞀オリゞンポリシヌず、画面ずAPIを分けたずきに出る゚ラヌの意味」で扱いたした。

    䜕が同じで、䜕が違うのか

    倖郚のサヌビスの API ず、自分のアプリの䞭の API は、どちらも HTTP のリク゚ストを受けお、応答を返す窓口です。仕組みずしおは同じものです。違うのは、誰が䜜り、誰が呌び、窓口の圢を誰が決めるかです。

    画像
    倖郚のサヌビスの API ず、自分のアプリの䞭の API の比范。仕組みは同じで、䜜る人・呌ぶ人・決める人が違う

    ここで泚意したいのは、「自分のアプリの䞭の API」は、倖から呌べないわけではないこずです。Next.js の文曞は、Route Handlers を「public HTTP endpoints」10公開された HTTP の窓口ずし、「Any client can access them.」10どのクラむアント、぀たり呌ぶ偎のプログラムからでも呌べるず説明しおいたす。そのうえで、呌べる人を限るには、ログむンの確認などの仕組みを入れるよう求めおいたす10。

    実際に、䜜ったアプリの /api/hello を、画面を通さずにコマンドから盎接呌んでみるず、そのたた JSON が返っおきたした。「自分の画面のための API」は、䜿う目的の話であっお、倖から芋えないずいう意味ではありたせん。

    $ curl -i http://localhost:3000/api/hello
    HTTP/1.1 200 OK
    content-type: application/json
    
    {"message":"こんにちは","time":"2026-11-06T21:16:20.973Z"}

    自分の API を守るログむンの確認ず、キャッシュ

    自分の画面から自分の API を呌ぶずき、「誰からの頌みか」は、倚くの堎合ログむンの仕組みで䌝えたす。ログむンしたブラりザヌは、サヌバヌから預かった Cookie を、同じサむトぞのリク゚ストに付けお送り返したす。サヌバヌはその Cookie からセッションを探し、ログむンしおいる人を芋分けたす。

    Cookie そのものの働きず、Cookie ずセッション・トヌクンでログむンが続く仕組みは、次の本の蚘事で扱いたした。

    もう぀気を぀けたいのが、API の応答も、ブラりザヌや CDN利甚者の近くに写しを眮くサヌバヌの集たりのキャッシュに保存されるこずがある点です。ログむンした人ごずに䞭身が倉わる応答が、共有のキャッシュに保存されるず、別の人にその応答が返るおそれがありたす。応答に Cache-Control の private などを付けお防ぐ方法は、次の蚘事で扱いたした。

    よくある組み合わせ自分の API を通しお倖郚の API を呌ぶ

    実際のアプリでは、぀目の API が、぀目の API を呌ぶ圢がよく䜿われたす。画面は自分のアプリの API を呌び、自分の API がサヌバヌの偎で倖郚の API を呌んで、結果を画面に返したす。こうするず、倖郚の API の鍵をサヌバヌの䞭だけに眮き、利甚者のブラりザヌに枡さずに枈みたす。

    Next.js の文曞は、このように画面のための窓口をサヌバヌの偎に眮く圢を「Backend for Frontend」10BFFず呌んでいたす。同じ文曞では、別のサヌバヌぞ頌みを取り次ぐずきに、リク゚ストの確認や、そのサヌバヌぞの認蚌、答えの䜜り盎しが芁る堎合は、Route Handlers を䜿うよう案内しおいたす10。倖郚の API を呌ぶずきに、鍵を環境倉数から読む䟋9も瀺されおいたす。

    画像
    画面 → 自分の API → 倖郚の API の順に呌ぶ圢。鍵はサヌバヌの䞭だけに眮く

    小さなアプリで確かめる

    この圢を、小さな Next.js のアプリで確かめたした。倖郚の倩気予報のサヌビスの代わりに、鍵がないず断る小さなサヌバヌを手元に立お、自分のアプリの /api/weather から、そのサヌバヌを呌ぶようにしたした。

    // app/api/weather/route.js自分のアプリの䞭の API
    export async function GET(request) {
      const city = request.nextUrl.searchParams.get('city') ?? 'kurume';
      const res = await fetch(`http://localhost:4000/v1/forecast?city=${encodeURIComponent(city)}`, {
        headers: { Authorization: `Bearer ${process.env.WEATHER_API_KEY}` },
      });
      // 倖郚の API が断ったずきは、502䞭継先で倱敗したこずを瀺す番号を返す
      if (!res.ok) return Response.json({ error: '倩気を取埗できたせんでした' }, { status: 502 });
      const data = await res.json();
      return Response.json({ city: data.city, weather: data.weather, max: data.max, min: data.min });
    }

    画面は、自分の API の /api/weather を呌ぶだけです。結果は次のずおりでした。

    • ブラりザヌで画面を開くず、倩気が衚瀺された。ブラりザヌが送ったのは、自分のアプリぞのリク゚スト/api/weatherだけで、倖郚のサヌバヌぞのリク゚ストはなかった

    • 倖郚のサヌバヌには、自分のアプリのサヌバヌから、鍵の付いたリク゚ストが届いおいた

    • 倖郚のサヌバヌを鍵なしで盎接呌ぶず、401認蚌の情報がないこずを瀺す番号で断られた

    • 自分の API の /api/hello を、関数を曞いおいないメ゜ッドの POST で呌ぶず、405そのメ゜ッドは受け付けおいないこずを瀺す番号が返った

    画像
    小さなアプリで確かめた結果。ブラりザヌは自分の API だけを呌び、鍵はサヌバヌから倖郚ぞ送られおいた

    鍵を画面の偎に眮くず、配られる

    Next.js では、環境倉数の名前を NEXT_PUBLIC_ で始めるず、その倀をブラりザヌでも䜿えるようになりたす。このずき倀は、アプリを組み立おるビルドするずきに、ブラりザヌに配る JavaScript のファむルぞ曞き蟌たれたす11。NEXT_PUBLIC_ で始たらない環境倉数は、サヌバヌの偎でしか䜿えたせん11。

    この動きも確かめたした。画面から倖郚のサヌバヌを盎接呌ぶペヌゞを぀足し、鍵を NEXT_PUBLIC_ で始たる環境倉数に入れおビルドするず、ブラりザヌに配る JavaScript のファむルの䞭に、鍵の文字列がそのたた入っおいたした。そのペヌゞを倖しおビルドし盎すず、配るファむルの䞭から鍵の文字列は芋぀かりたせんでした。

    /api/weather が䜿っおいる鍵は、サヌバヌの偎で読むため、配るファむルには入っおいたせんでした。

    画像
    鍵を NEXT_PUBLIC_ の環境倉数に入れるず、ブラりザヌに配る JavaScript に曞き蟌たれる。サヌバヌの偎で読む鍵は配られない

    ブラりザヌに配られたファむルは、誰でも開いお読むこずができたす。OpenAI の JavaScript のラむブラリも、ブラりザヌで䜿う蚭定を初めは無効にしおいたす8。有効にする蚭定の名前は dangerouslyAllowBrowser危険を承知でブラりザヌで䜿うで、その危険を「exposes your secret API credentials in the client-side code」8秘密の資栌情報が、利甚者の手元で動くコヌドに出おしたうず説明しおいたす。

    倖郚の API の鍵は、画面の偎に眮かず、自分の API を通しお䜿うのが基本です。

    API の圢を決める考え方REST

    自分のアプリの䞭の API を䜜るずきは、URL やメ゜ッドの決め方を、自分で考えるこずになりたす。たずえば「予玄の䞀芧」「件の予玄」「予玄の取り消し」を、どのような URL ずメ゜ッドで衚すかです。この決め方の考え方ずしお広く知られおいるのが REST です。

    REST の考え方ず、ステヌタスコヌドの䜿い分けは、次の蚘事で扱いたした。

    画像
    この蚘事ず、関連する蚘事の関係。API の意味ず皮類を抌さえおから、それぞれの蚘事ぞ進む

    たずめ

    • API は、プログラムが䜿うための窓口。決められた呌び出し方を守れば、䞭の仕組みを知らなくおも機胜を䜿える

    • 「API」ず呌ばれるものは、同じプログラムの䞭で呌ぶ API、倖郚のサヌビスの API、自分のアプリの䞭の API の぀に分けるず敎理しやすい

    • 倖郚のサヌビスの API ず自分のアプリの䞭の API は、どちらも HTTP のリク゚ストず応答でやりずりする Web API。違うのは、誰が䜜り、誰が呌び、圢を誰が決めるか

    • 自分のアプリの䞭の API も、倖から呌べる。呌べる人を限るにはログむンの確認が、人ごずの応答にはキャッシュの蚭定が芁る

    • 倖郚の API の鍵は、画面の偎に眮かない。自分の API を通しお、サヌバヌの偎から䜿う

    画像
    この蚘事のたずめ。「API」ず呌ばれる぀のものず、倖郚の API を䜿うずきの基本の圢

    「API」ずいう蚀葉が出おきたら、「誰が䜜った窓口を、誰が呌んでいるのか」を考えるず、話が芋えやすくなりたす。OpenAI API も Next.js の /api/〜 も、HTTP で頌んで答えを受け取る窓口ずいう点では同じものです。

    免責事項

    この蚘事は、筆者が個人ずしお調べたこずや経隓をもずに、執筆時点の内容をたずめたものです。分かりやすさを優先し、现かい条件や䟋倖を省いおいる堎合がありたす。

    動䜜は、Next.js 16.4.5・Node.js 22.23.4・Chromium 153 で、怜蚌甚の小さなアプリを䜿っお確かめたもので、バヌゞョンや蚭定によっお倉わるこずがありたす。倖郚のサヌビスの利甚の条件や料金は、各サヌビスの芏玄や公匏の情報で最新の内容を確認しおください。

    補品の仕様などは倉わるこずがありたす。この蚘事の内容を利甚しお生じた損害に぀いおは、責任を負いかねたす。

    NDシステムズに぀いお

    NDシステムズは、犏岡県久留米垂を拠点に、ホヌムペヌゞの制䜜、業務に合わせた事務のシステムの開発、AI・DX支揎を行っおいたす。たずはお気軜に無料盞談でご盞談ください。

    参考文献

    1. APIMDN Web Docs 甚語集

    2. Web APIMDN Web Docs

    3. HTTP の抂芁MDN Web Docs

    4. JSONMDN Web Docs 甚語集

    5. open-meteo/open-meteoOpen-Meteo、GitHub英語

    6. Weather Forecast APIOpen-Meteo英語

    7. API Overview - AuthenticationOpenAI英語

    8. openai/openai-nodeOpenAI、GitHub英語

    9. Route HandlersNext.js Docs英語

    10. How to use Next.js as a backend for your frontendNext.js Docs英語

    11. How to use environment variables in Next.jsNext.js Docs英語

     
     
    犏岡県久留米垂のNDシステムズです。IT・AI、語孊、䌚蚈、数孊、九州北郚の颚景などに぀いお、調べお考えたこずを曞いおいたす。蚘事は筆者が個人ずしお調べた執筆時点の内容で、専門家の助蚀ではありたせん。最新の情報は出兞でご確認ください。

    あなたぞのおすすめ