Go言語でREST APIを作る設計と実装パターン完全ガイド！初心者でもわかるAPI開発

1. Go言語とREST APIとは？

1. Go言語とREST APIとは？

Go言語は、シンプルで速く動くプログラミング言語です。Googleが開発しており、WebサービスやAPI開発で多く使われています。REST APIとは、インターネット上でデータをやり取りするための決まりごとです。難しく感じるかもしれませんが、「注文すると料理が運ばれてくるレストラン」のような仕組みだと考えると分かりやすいです。注文内容がリクエスト、料理がレスポンスにあたります。

2. REST APIの基本構造を理解しよう

2. REST APIの基本構造を理解しよう

REST APIでは、「URL」「HTTPメソッド」「データ形式」が重要です。URLは住所、HTTPメソッドは動作の種類です。たとえばGETは「取得」、POSTは「追加」を意味します。Go言語では、これらを標準ライブラリだけで扱えます。特別な道具を用意しなくても、最初からAPI開発ができる点が大きな特徴です。

3. 最小構成のREST APIを作ってみよう

3. 最小構成のREST APIを作ってみよう

まずは、最もシンプルなREST APIを作ります。これは「アクセスすると文字を返すだけ」のAPIです。動作の流れを理解することが目的なので、内容はとても簡単です。

package main

import (
    "fmt"
    "net/http"
)

func handler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "Hello API")
}

func main() {
    http.HandleFunc("/", handler)
    http.ListenAndServe(":8080", nil)
}

このコードでは、8080番ポートでサーバーを起動しています。ブラウザからアクセスすると文字が表示されます。これがGo言語で作るREST APIの第一歩です。

4. JSON形式でデータを返す設計

4. JSON形式でデータを返す設計

REST APIでは、JSONという形式でデータを返すことが一般的です。JSONは「名前と値のセット」で表現され、人にも機械にも読みやすい形式です。Go言語では構造体を使ってJSONを簡単に扱えます。

package main

import (
    "encoding/json"
    "net/http"
)

type Message struct {
    Text string `json:"text"`
}

func handler(w http.ResponseWriter, r *http.Request) {
    msg := Message{Text: "Hello JSON"}
    json.NewEncoder(w).Encode(msg)
}

func main() {
    http.HandleFunc("/message", handler)
    http.ListenAndServe(":8080", nil)
}

このように設計すると、アプリや他のサービスがデータを受け取りやすくなります。REST API設計では、データ形式をそろえることがとても重要です。

5. HTTPメソッドで処理を分ける考え方

5. HTTPメソッドで処理を分ける考え方

REST APIでは、同じURLでもHTTPメソッドによって動作を変えます。これは「同じドアでも、押すか引くかで動きが違う」ようなイメージです。Go言語ではリクエスト情報を確認して処理を分けます。

func handler(w http.ResponseWriter, r *http.Request) {
    if r.Method == http.MethodGet {
        w.Write([]byte("GET request"))
    } else if r.Method == http.MethodPost {
        w.Write([]byte("POST request"))
    }
}

この設計により、APIの役割が明確になり、保守しやすい構成になります。

6. ルーティング設計の基本パターン

6. ルーティング設計の基本パターン

ルーティングとは、URLごとに処理を分ける設計です。REST APIでは、意味のあるURLを作ることが重要です。たとえば「/users」や「/products」のように、扱うデータが分かる名前を使います。

http.HandleFunc("/users", usersHandler)
http.HandleFunc("/products", productsHandler)

このような設計にすると、APIの構造が直感的になり、初めて見た人でも理解しやすくなります。

7. エラーハンドリングの考え方

7. エラーハンドリングの考え方

API開発では、失敗したときの対応も大切です。エラーは「うまくいかなかった理由を伝えるメッセージ」です。Go言語では、ステータスコードを使って状況を伝えます。404は「見つからない」、500は「内部エラー」を意味します。

8. シンプルで分かりやすい設計を心がける

8. シンプルで分かりやすい設計を心がける

初心者向けのREST API設計では、機能を詰め込みすぎないことが大切です。Go言語の強みは、少ないコードで分かりやすく書ける点です。役割ごとに処理を分け、URLと動作が自然に結びつく設計を意識しましょう。これが長く使えるAPIにつながります。

まとめ

まとめ

Go言語でREST APIを作るときは、まずAPIが何のために存在するのかを理解することが大切です。APIは、アプリケーションやサービス同士が情報をやり取りするための窓口です。利用する側がリクエストを送り、API側が処理を行ってレスポンスを返すという流れが基本になります。Go言語では標準ライブラリのnet/httpを利用することで、特別なフレームワークを導入しなくてもシンプルなREST APIを作成できます。

REST APIを設計するときに重要になるのが、URL、HTTPメソッド、レスポンスとして返すデータ形式です。URLはどの情報を扱うのかを表し、HTTPメソッドはその情報に対して何を行いたいのかを表します。例えば利用者情報を扱うAPIならusersというURLを用意し、情報を取得する場合はGET、情報を追加する場合はPOSTというように役割を分けます。この考え方を理解すると、API全体の構造を整理しやすくなります。

Go言語ではnet/httpだけでもREST APIを作れる

Go言語のREST API開発で最初に覚えておきたいのがnet/httpパッケージです。Go言語にはWebサーバーやHTTP通信を扱うための機能が標準ライブラリとして用意されています。そのため、小さなAPIであれば外部のフレームワークを使わなくても実装できます。

APIを作る基本的な流れは、URLに対する処理を登録し、指定したポート番号でWebサーバーを起動することです。利用者がそのURLへアクセスすると、登録しておいた関数が呼び出され、レスポンスを返します。

package main

import (
    "fmt"
    "net/http"
)

func helloHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "Hello API")
}

func main() {
    http.HandleFunc("/", helloHandler)
    http.ListenAndServe(":8080", nil)
}

このような小さなプログラムでもWebサーバーとして動作します。八千八十番ポートで待ち受け、アクセスがあるとHello APIという文字を返します。Go言語初心者がREST APIを学ぶときは、まずこの最小構成を実際に動かして、リクエストを受け取ってレスポンスを返すという基本的な流れを確認すると理解しやすくなります。

REST APIではJSON形式のレスポンスがよく使われる

REST APIでは、単純な文字列だけでなくJSON形式でデータを返すことがよくあります。JSONは項目名と値を組み合わせて表現するデータ形式で、Webアプリケーションやスマートフォンアプリなど、さまざまなシステムから利用しやすい特徴があります。

Go言語では構造体とencoding/jsonパッケージを利用することで、Go言語のデータをJSON形式へ変換してレスポンスとして返せます。構造体を使うと、どの項目をAPIから返すのかをプログラム上でも整理しやすくなります。

package main

import (
    "encoding/json"
    "net/http"
)

type User struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

func userHandler(w http.ResponseWriter, r *http.Request) {
    user := User{
        Name: "田中",
        Age:  25,
    }

    json.NewEncoder(w).Encode(user)
}

func main() {
    http.HandleFunc("/users", userHandler)
    http.ListenAndServe(":8080", nil)
}

{"name":"田中","age":25}

この例では、利用者を表す構造体を作成し、その内容をJSON形式へ変換して返しています。REST APIでは、どのURLからどのようなJSONデータが返るのかをそろえておくことで、APIを利用する側も処理を書きやすくなります。

GETとPOSTは役割を分けて考える

REST APIではHTTPメソッドによって操作の目的を分けます。記事で紹介したGETはデータを取得するときに利用し、POSTは新しいデータを追加したいときに利用します。同じURLであっても、HTTPメソッドによって異なる処理を行わせることができます。

Go言語ではhttp.Requestに含まれるMethodを確認することで、送られてきたHTTPメソッドを判断できます。処理の目的によってGETとPOSTを分ければ、APIを利用する側から見ても何を行うリクエストなのか理解しやすくなります。

func usersHandler(w http.ResponseWriter, r *http.Request) {
    if r.Method == http.MethodGet {
        w.Write([]byte("利用者情報を取得します"))
        return
    }

    if r.Method == http.MethodPost {
        w.Write([]byte("利用者情報を追加します"))
        return
    }

    http.Error(w, "対応していないメソッドです", http.StatusMethodNotAllowed)
}

この例では、GETの場合とPOSTの場合で処理を分けています。それ以外のHTTPメソッドが送られてきた場合には、対応していないことをエラーとして返しています。REST API設計では、利用できる操作と利用できない操作を明確にすることも大切です。

URLは扱うデータが分かる名前にする

REST APIを分かりやすくするためには、ルーティング設計も重要です。ルーティングとは、URLごとにどの処理を実行するかを決めることです。利用者を扱うならusers、商品を扱うならproductsというように、URLを見ただけで何のデータを扱っているのか分かる名前にすると理解しやすくなります。

http.HandleFunc("/users", usersHandler)
http.HandleFunc("/products", productsHandler)

URLに意味を持たせておくと、APIの数が増えても整理しやすくなります。何でも一つのURLで処理するのではなく、利用者、商品、注文など扱う対象ごとに分けることで、Go言語のプログラム側も役割を整理できます。

リクエストとレスポンスの流れを意識する

REST APIでは、利用する側からリクエストが送られ、その内容をGo言語のWebサーバーが受け取ります。サーバー側ではURLやHTTPメソッドなどを確認し、必要な処理を実行します。そして処理結果をレスポンスとして返します。

初心者のうちは、APIという言葉だけを見ると難しく感じるかもしれません。しかし、どのURLに、どのHTTPメソッドで、どのようなリクエストが届き、最後に何をレスポンスとして返すのかという順番で考えると整理しやすくなります。

• URLは、どのデータや機能を利用するのかを表します。
• GETは、データを取得したい場合に利用します。
• POSTは、新しいデータを追加したい場合に利用します。
• JSONは、APIでデータをやり取りするときによく使われる形式です。
• レスポンスは、API側から利用する側へ返す処理結果です。

REST APIではエラー時の返し方も重要

APIは常に正常に処理できるとは限りません。指定されたデータが存在しない場合や、サーバー内部で処理に失敗した場合などがあります。そのようなときに、ただ何も返さないのではなく、どのような問題が起きたのかをステータスコードなどで伝えることが重要です。

代表的なものとして、要求された情報が見つからない場合には四百四、サーバー内部で問題が起きた場合には五百というステータスコードがあります。APIを利用する側は、この情報を確認することで処理が成功したのか失敗したのかを判断できます。

func userHandler(w http.ResponseWriter, r *http.Request) {
    found := false

    if !found {
        http.Error(w, "利用者が見つかりません", http.StatusNotFound)
        return
    }

    w.Write([]byte("利用者が見つかりました"))
}

このようにGo言語ではhttp.Errorを利用してエラー内容とステータスコードを返すことができます。REST APIでは正常時のレスポンスだけでなく、失敗した場合にどのようなレスポンスを返すかまで考えることが重要です。

シンプルなAPI設計は後から修正しやすい

Go言語でREST APIを作るときは、最初から大量の機能を一つの処理へ詰め込まないことが大切です。利用者を扱う処理、商品を扱う処理、JSONを返す処理など、役割を分けておくとプログラムを読みやすくできます。

特にAPIの機能が増えると、一つの関数にすべてを書いたプログラムは修正しにくくなります。URLごとにハンドラーを分けたり、データを表す構造体を用意したりすることで、どこに何が書かれているのかを判断しやすくなります。

Go言語はシンプルな書き方を重視しているため、REST APIでも複雑な仕組みをいきなり導入するのではなく、最小構成から少しずつ機能を追加していく学習方法が向いています。最初は文字列を返すAPI、次にJSONを返すAPI、さらにGETとPOSTを分けるAPIというように段階的に学習するとよいでしょう。

初心者はREST APIの全体の流れから覚えよう

Go言語でREST API開発を学ぶときは、個別の命令を暗記するよりも、リクエストからレスポンスまでの流れを理解することが大切です。まずクライアントからURLへリクエストが送られます。Go言語のWebサーバーがそのリクエストを受け取り、登録されているハンドラーを実行します。ハンドラーではHTTPメソッドや必要な情報を確認し、最後に文字列やJSONなどをレスポンスとして返します。

この基本的な流れが理解できれば、利用者一覧を返すAPIや商品情報を返すAPIなどへ少しずつ発展させられます。REST APIは特別な仕組みだけで作られているのではなく、URL、HTTPメソッド、リクエスト、レスポンス、JSON、ステータスコードといういくつかの基本要素を組み合わせて作られています。

最初はブラウザからアクセスして文字列を表示するだけでも十分です。その後、構造体をJSONへ変換して返し、さらにGETとPOSTで処理を分けるようにすると、REST APIらしい構造を段階的に理解できます。

Go言語のREST API開発で覚えておきたい用語

Go言語でAPI開発を進めると、REST API、HTTP、URL、GET、POST、JSON、ルーティング、ハンドラー、レスポンス、ステータスコード、net/http、encoding/jsonなどの言葉が繰り返し登場します。最初からすべての意味を完璧に覚える必要はありません。

URLは処理の入口、HTTPメソッドは操作の種類、ハンドラーは実際に処理する関数、JSONはデータを返す形式、ステータスコードは処理結果を伝える番号というように、それぞれの役割を一つずつ整理すると理解しやすくなります。

Go言語は標準ライブラリだけでも基本的なREST APIを作ることができるため、Web API開発の仕組みそのものを学ぶ教材としても分かりやすい特徴があります。まずは小さなAPIを実際に起動し、URLへアクセスしてレスポンスを確認するところから始めてみましょう。

REST APIを設計するときは、単に動作することだけではなく、利用する側から見て分かりやすいことも重要です。どのURLを使えばよいのか、GETとPOSTのどちらを使うのか、成功した場合にどのようなJSONが返るのか、失敗した場合にどのステータスコードが返るのかを分かりやすくしておくことで、利用しやすいAPIになります。

Go言語によるREST API開発の基本は、net/httpでサーバーを作ることから始まり、ルーティング、HTTPメソッド、JSONレスポンス、エラーハンドリングへとつながっていきます。この順番を意識して学習することで、初心者でも少しずつ本格的なWeb APIの設計と実装へ進むことができます。