Go言語でJSON APIを作る基本！エンコード・デコード例

1. JSON APIの基本構造

1. JSON APIの基本構造

JSON APIとは、Web上でデータをやり取りするための仕組みです。Goではhttp.HandleFuncでルートを設定し、json.NewEncoderでデータを返すことで簡単に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}
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(user)
}

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

このコードでは/userにアクセスすると、JSON形式でユーザー情報が返されます。w.Header().Set("Content-Type", "application/json")は、返すデータの形式をJSONとブラウザに知らせる設定です。

2. JSONのデコード方法

2. JSONのデコード方法

APIでは、クライアントから送られたJSONデータをGoの構造体に変換して扱うことも重要です。これをデコードと呼びます。

func createUserHandler(w http.ResponseWriter, r *http.Request) {
    if r.Method == "POST" {
        var user User
        json.NewDecoder(r.Body).Decode(&user)
        w.Header().Set("Content-Type", "application/json")
        json.NewEncoder(w).Encode(user)
    } else {
        http.Error(w, "POSTメソッドでアクセスしてください", http.StatusMethodNotAllowed)
    }
}

func main() {
    http.HandleFunc("/create-user", createUserHandler)
    http.ListenAndServe(":8080", nil)
}

このコードでは、POSTメソッドで送られたJSONデータをuser構造体に変換し、再度JSONとして返しています。これにより、データの受け取りと送信が簡単に行えます。

3. JSON API作成のポイント

3. JSON API作成のポイント

• Goの標準ライブラリencoding/jsonを使うことで、簡単にJSONのエンコード・デコードが可能。
• 構造体のフィールドに`json:"フィールド名"`タグを付けると、JSONのキー名を自由に設定できる。
• http.HandleFuncでURLごとに処理を設定できるので、複数のAPIを作るのも簡単。
• POSTリクエストの処理ではjson.NewDecoder(r.Body)を使い、リクエストボディからJSONを読み取る。
• 返すデータはw.Header().Set("Content-Type", "application/json")でJSON形式であることを明示。

これらのポイントを押さえれば、Go言語で簡単にJSON APIを作成でき、データのやり取りやWebサービス開発に役立てられます。

4. JSONレスポンスの形式を整える

4. JSONレスポンスの形式を整える

JSON APIを実装する際は、単にデータを返すだけでなく、レスポンスの形式をある程度そろえておくと扱いやすくなります。たとえば、実際の開発では「データ本体」と「結果の状態」を分けて返すケースも多くあります。

このような形式にしておくと、クライアント側で処理結果を判断しやすくなり、API全体の見通しも良くなります。

type Response struct {
    Status string `json:"status"`
    Data   User   `json:"data"`
}

func userHandler(w http.ResponseWriter, r *http.Request) {
    res := Response{
        Status: "success",
        Data:   User{Name: "太郎", Age: 25},
    }
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(res)
}

この例では、ユーザー情報に加えて処理結果を示すstatusを含めています。APIの規模が大きくなるほど、このような整理が役立ちます。

5. デコード時のエラーを意識する

5. デコード時のエラーを意識する

JSONをデコードする際は、必ずしも正しい形式のデータが送られてくるとは限りません。そのため、デコード時のエラーを確認することが重要です。エラーを無視すると、意図しないデータが処理されてしまう可能性があります。

Goでは、Decodeの戻り値としてエラーを受け取れるので、それを使って安全に処理を進めます。

var user User
err := json.NewDecoder(r.Body).Decode(&user)
if err != nil {
    http.Error(w, "JSONの形式が正しくありません", http.StatusBadRequest)
    return
}

このようにエラー処理を加えることで、JSON APIとしての信頼性が高まり、想定外の入力にも対応しやすくなります。

6. JSON APIを拡張していく考え方

6. JSON APIを拡張していく考え方

基本的なJSON APIを作れるようになると、次は機能を少しずつ拡張していく段階に入ります。たとえば、複数のユーザーを配列で返したり、条件に応じて返すデータを変えたりといった処理です。

Goでは、スライスと構造体を組み合わせることで、複数データのJSON返却も簡単に実装できます。

users := []User{
    {Name: "太郎", Age: 25},
    {Name: "花子", Age: 30},
}

w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(users)

このように、基本のエンコード・デコードの考え方は変えずに、扱うデータの形だけを広げていくことで、実践的なJSON APIへと発展させることができます。

まとめ

まとめ

この記事では、Go言語を使ってJSON APIを作成するための基本的な考え方と実装方法について解説してきました。 JSON APIは、Webアプリケーションやスマートフォンアプリ、外部サービスとの連携など、さまざまな場面で使われる重要な仕組みです。 Go言語は標準ライブラリが非常に充実しているため、特別なフレームワークを使わなくても、シンプルなコードでJSONの送受信を実現できます。

まず、JSON APIの基本として、HTTPサーバーを立ち上げ、特定のURLにアクセスされたときに処理を行う方法を確認しました。 http.HandleFuncを使えば、URLごとに処理を分けることができ、APIの構造も直感的に理解できます。 また、レスポンスとしてJSONを返す場合は、encoding/jsonパッケージの json.NewEncoderを使うことで、構造体をそのままJSON形式に変換できる点が大きな特徴です。 これにより、手作業でJSON文字列を組み立てる必要がなく、ミスも減らせます。

次に、JSONのデコードについて学びました。 APIを作るうえでは、データを返すだけでなく、クライアントから送られてくるJSONデータを受け取って処理することも欠かせません。 Goでは、json.NewDecoder(r.Body)を使うことで、リクエストボディに含まれるJSONを構造体に直接変換できます。 この仕組みを使えば、POSTリクエストで送信されたデータを安全かつ簡潔に扱うことができ、 ユーザー登録やデータ作成用のAPIなど、実用的な機能を実装しやすくなります。

JSON APIを設計する際には、構造体に付けるJSONタグも重要なポイントです。 Goの構造体のフィールド名は大文字から始める必要がありますが、 JSONとして返すキー名は小文字やスネークケースにしたい場面も多くあります。 そのような場合に、`json:"name"`のようなタグを付けることで、 GoのコードとJSONの表現をうまく分離できます。 この工夫によって、APIの仕様が分かりやすくなり、他の開発者やクライアント側との連携もスムーズになります。

また、HTTPメソッドの扱い方も重要です。 GETリクエストは主にデータの取得、POSTリクエストはデータの作成や送信に使われることが多く、 Goではr.Methodを確認することで、リクエストの種類に応じた処理を簡単に分けられます。 想定していないメソッドでアクセスされた場合は、ステータスコードを返してエラーを通知することで、 APIとしての使いやすさや安全性を高めることができます。

以下は、この記事で学んだ内容を整理した、シンプルなJSON APIのサンプルです。 ユーザー情報をJSONで返す基本的な形を、あらためて確認しておきましょう。

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

func userHandler(w http.ResponseWriter, r *http.Request) {
    user := User{Name: "花子", Age: 30}
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(user)
}

このように、Go言語のJSON APIは「構造体を定義する」「エンコード・デコードする」「HTTPでやり取りする」 という基本の流れを押さえるだけで、すぐに実用レベルの実装が可能です。 初心者の方は、まずはこの形をしっかり理解し、小さなAPIから作ってみることをおすすめします。