ข้ามไปยังเนื้อหาหลัก
เวอร์ชัน: ล่าสุด

การกำหนดเวอร์ชัน API

จัดการการเปลี่ยนแปลงเวอร์ชัน API อย่างเหมาะสมและรักษาความเข้ากันได้แบบย้อนหลัง เรียนรู้เกี่ยวกับกลยุทธ์การกำหนดเวอร์ชันของ Omise วิธีการระบุเวอร์ชัน และแนวทางปฏิบัติที่ดีที่สุดสำหรับการอัปเกรด

ภาพรวม​

Omise ใช้การกำหนดเวอร์ชัน API แบบวันที่เพื่อแนะนำการปรับปรุงโดยไม่ทำลายการผสานที่มีอยู่ แต่ละเวอร์ชันจะตั้งชื่อตามวันที่เผยแพร่ (รูปแบบ YYYY-MM-DD) คุณสามารถควบคุมเวอร์ชัน API ที่การผสานของคุณใช้เพื่อให้มั่นใจในความเสถียรและวางแผนการอัปเกรดตามกำหนดการของคุณเอง

เริ่มต้นอย่างรวดเร็ว
  • เวอร์ชันปัจจุบัน: 2019-05-29
  • ใช้เฮดเดอร์ Omise-Version เพื่อระบุเวอร์ชัน
  • ไม่มีเฮดเดอร์ = เวอร์ชันเริ่มต้นของบัญชี
  • เวอร์ชันไม่มีวันเปลี่ยนแปลง - การผสานของคุณยังคงเสถียร
  • วางแผนการอัปเกรดเมื่อคุณต้องการฟีเจอร์ใหม่

เวอร์ชัน API ปัจจุบัน​

เวอร์ชันล่าสุด: 2019-05-29​

วันที่เผยแพร่: May 29, 2019

นี่คือเวอร์ชันเสถียรปัจจุบันของ Omise API การผสานใหม่ทั้งหมดควรใช้เวอร์ชันนี้

curl https://api.omise.co/charges \
  -u skey_test_...: \
  -H "Omise-Version: 2019-05-29"

การกำหนดเวอร์ชันทำงานอย่างไร​

รูปแบบเวอร์ชัน​

เวอร์ชัน Omise API ใช้การตั้งชื่อตามวันที่:

YYYY-MM-DD

ตัวอย่าง:

  • 2019-05-29 - เผยแพร่ May 29, 2019
  • 2017-11-02 - เผยแพร่ November 2, 2017
  • 2015-11-17 - เผยแพร่ November 17, 2015

การระบุเวอร์ชัน API​

คุณสามารถระบุเวอร์ชัน API ได้สองวิธี:

1. เฮดเดอร์ต่อคำขอ (แนะนำ)​

ใช้เฮดเดอร์ Omise-Version:

curl https://api.omise.co/charges \
  -u skey_test_...: \
  -H "Omise-Version: 2019-05-29" \
  -X POST \
  -d "amount=100000" \
  -d "currency=thb"

ข้อดี:

  • ✅ การจัดการเวอร์ชันที่ชัดเจนต่อคำขอ
  • ✅ ง่ายต่อการทดสอบเวอร์ชันใหม่
  • ✅ สามารถใช้เวอร์ชันที่ต่างกันสำหรับการดำเนินการที่ต่างกัน
  • ✅ แทนที่ค่าเริ่มต้นของบัญชี

2. เวอร์ชันเริ่มต้นของบัญชี​

ตั้งค่าเวอร์ชันเริ่มต้นในแดชบอร์ด:

  1. เข้าสู่ระบบ Omise Dashboard
  2. ไปที่ Settings → API Version
  3. เลือกเวอร์ชัน
  4. บันทึก

คำขอทั้งหมดที่ไม่มีเฮดเดอร์ Omise-Version จะใช้เวอร์ชันนี้

พฤติกรรมเวอร์ชัน​

เวอร์ชันทำงานอย่างไร​

  1. เวอร์ชันไม่เปลี่ยนแปลง - พฤติกรรมของเวอร์ชันไม่มีวันเปลี่ยน
  2. เวอร์ชันใหม่แนะนำการเปลี่ยนแปลง - การเปลี่ยนแปลงที่ทำลายเฉพาะในเวอร์ชันใหม่เท่านั้น
  3. คุณควบคุมการอัปเกรด - เลือกใช้เวอร์ชันใหม่อย่างชัดเจน
  4. รองรับเวอร์ชันเก่า - เวอร์ชันเดิมยังคงใช้งานได้

ตัวอย่างไทม์ไลน์​

2015-11-17 → สร้างการผสาน
    ↓
2017-11-02 → เผยแพร่เวอร์ชันใหม่
    ↓        (การผสานยังคงใช้ 2015-11-17)
    ↓
2019-05-29 → เผยแพร่เวอร์ชันใหม่
    ↓        (การผสานยังคงใช้ 2015-11-17)
    ↓
วันนี้      → อัปเกรดเป็น 2019-05-29
    ↓        (เลือกใช้เมื่อพร้อม)

การระบุเวอร์ชันในโค้ด​

Ruby​

require 'omise'

Omise.api_key = ENV['OMISE_SECRET_KEY']
Omise.api_version = '2019-05-29'

# คำขอทั้งหมดใช้เวอร์ชันที่ระบุ
charge = Omise::Charge.create({
  amount: 100000,
  currency: 'thb',
  card: token
})

Python​

import omise

omise.api_secret = os.environ['OMISE_SECRET_KEY']
omise.api_version = '2019-05-29'

# คำขอทั้งหมดใช้เวอร์ชันที่ระบุ
charge = omise.Charge.create(
    amount=100000,
    currency='thb',
    card=token
)

PHP​

<?php
require_once 'vendor/autoload.php';

define('OMISE_SECRET_KEY', getenv('OMISE_SECRET_KEY'));
define('OMISE_API_VERSION', '2019-05-29');

OmiseCharge::create([
    'amount' => 100000,
    'currency' => 'thb',
    'card' => $token
]);

Node.js​

const omise = require('omise')({
  secretKey: process.env.OMISE_SECRET_KEY,
  omiseVersion: '2019-05-29'
});

// คำขอทั้งหมดใช้เวอร์ชันที่ระบุ
const charge = await omise.charges.create({
  amount: 100000,
  currency: 'thb',
  card: token
});

Go​

package main

import (
    "github.com/omise/omise-go"
    "github.com/omise/omise-go/operations"
)

func main() {
    client, _ := omise.NewClient(
        os.Getenv("OMISE_PUBLIC_KEY"),
        os.Getenv("OMISE_SECRET_KEY"),
    )

    // ตั้งค่าเวอร์ชัน API
    client.APIVersion = "2019-05-29"

    charge, _ := client.CreateCharge(&operations.CreateCharge{
        Amount:   100000,
        Currency: "thb",
        Card:     token,
    })
}

cURL​

# ระบุเวอร์ชันในเฮดเดอร์
curl https://api.omise.co/charges \
  -u skey_test_...: \
  -H "Omise-Version: 2019-05-29" \
  -X POST \
  -d "amount=100000" \
  -d "currency=thb" \
  -d "card=tokn_test_..."

การเปลี่ยนแปลงที่ทำลายและไม่ทำลาย​

การเปลี่ยนแปลงที่ทำลาย​

การเปลี่ยนแปลงที่ทำลายจะแนะนำเฉพาะในเวอร์ชัน API ใหม่เท่านั้น:

ตัวอย่าง:

  • การลบ API endpoint
  • การลบฟิลด์การตอบกลับ
  • การเปลี่ยนประเภทฟิลด์การตอบกลับ
  • การเปลี่ยนพารามิเตอร์ที่จำเป็น
  • การเปลี่ยนรหัสข้อผิดพลาด
  • การเปลี่ยนพฤติกรรมที่ส่งผลต่อโฟลว์ที่มีอยู่

วิธีการจัดการของ Omise:

  • ✅ เผยแพร่เป็นเวอร์ชันใหม่ (วันที่ใหม่)
  • ✅ เวอร์ชันเก่ายังคงทำงาน
  • ✅ เลือกใช้เมื่อพร้อม
  • ✅ จัดเตรียมคู่มือการย้ายข้อมูล

การเปลี่ยนแปลงที่ไม่ทำลาย​

การเปลี่ยนแปลงที่ไม่ทำลายอาจถูกเพิ่มในทุกเวอร์ชัน:

ตัวอย่าง:

  • เพิ่ม API endpoint ใหม่
  • เพิ่มฟิลด์การตอบกลับใหม่
  • เพิ่มพารามิเตอร์เสริมใหม่
  • เพิ่มรหัสข้อผิดพลาดใหม่
  • เพิ่มประเภทเหตุการณ์ใหม่
  • การปรับปรุงประสิทธิภาพ

วิธีจัดการ:

  • ✅ เพิกเฉยฟิลด์ที่ไม่รู้จักในการตอบกลับ
  • ✅ อย่าพึ่งพาลำดับฟิลด์
  • ✅ จัดการค่าที่ไม่คาดคิดอย่างเหมาะสม
  • ✅ ทดสอบด้วยข้อมูลที่ใกล้เคียงกับการผลิต
ความเข้ากันได้ล่วงหน้า

สร้างการผสานของคุณให้จัดการฟิลด์ใหม่อย่างเหมาะสม:

// ✅ ดี - เพิกเฉยฟิลด์ที่ไม่รู้จัก
const { id, amount, status } = charge;

// ❌ ไม่ดี - เสียเมื่อเพิ่มฟิลด์ใหม่
const charge = { id, amount, status }; // สมมติเฉพาะฟิลด์เหล่านี้

ทรัพยากรที่เกี่ยวข้อง​

ถัดไป: เรียนรู้เกี่ยวกับ การจำกัดอัตรา เพื่ออยู่ภายในขีดจำกัด API และจัดการข้อผิดพลาดการจำกัดอัตรา