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

API Versioning

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

ภาพรวม​

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

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

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

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

Released: 29 พฤษภาคม 2019

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

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

Versioning ทำงานอย่างไร​

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

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

YYYY-MM-DD

ตัวอย่าง:

  • 2019-05-29 - release 29 พฤษภาคม 2019
  • 2017-11-02 - release 2 พฤศจิกายน 2017
  • 2015-11-17 - release 17 พฤศจิกายน 2015

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

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

1. Per-Request Header (แนะนำ)​

ใช้ Omise-Version header:

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

ข้อดี:

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

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

ตั้งเวอร์ชันเริ่มต้นใน Dashboard:

  1. ล็อกอินที่ Omise Dashboard
  2. ไปที่ Settings → API Version
  3. เลือกเวอร์ชัน
  4. บันทึก

requests ทั้งหมดที่ไม่มี Omise-Version header จะใช้เวอร์ชันนี้

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

Ruby​

require 'omise'

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

# requests ทั้งหมดใช้เวอร์ชันที่ระบุ
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'

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

Node.js​

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

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

cURL​

# ระบุเวอร์ชันใน header
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_..."

Breaking vs Non-Breaking Changes​

Breaking Changes​

Breaking changes จะ แนะนำในเวอร์ชัน API ใหม่เท่านั้น:

ตัวอย่าง:

  • การลบ API endpoints
  • การลบ response fields
  • การเปลี่ยนประเภท response fields
  • การเปลี่ยนพารามิเตอร์ที่จำเป็น
  • การเปลี่ยน error codes
  • การปรับเปลี่ยนพฤติกรรมที่ส่งผลต่อ flows ที่มีอยู่

วิธีที่ Omise จัดการ:

  • ✅ Release เป็นเวอร์ชันใหม่ (วันที่ใหม่)
  • ✅ เวอร์ชันเก่ายังทำงานได้
  • ✅ คุณเลือกใช้เมื่อพร้อม
  • ✅ มีคู่มือการ migrate

Non-Breaking Changes​

Non-breaking changes อาจถูกเพิ่มในทุกเวอร์ชัน:

ตัวอย่าง:

  • การเพิ่ม API endpoints ใหม่
  • การเพิ่ม response fields ใหม่
  • การเพิ่มพารามิเตอร์ที่ไม่บังคับใหม่
  • การเพิ่ม error codes ใหม่
  • การเพิ่ม event types ใหม่
  • การปรับปรุงประสิทธิภาพ

วิธีจัดการ:

  • ✅ ละเว้น fields ที่ไม่รู้จักใน responses
  • ✅ อย่าพึ่งพาลำดับ fields
  • ✅ จัดการค่าที่ไม่คาดคิดอย่างเหมาะสม
  • ✅ ทดสอบกับข้อมูลที่คล้ายกับ production
Forward Compatibility

สร้างการเชื่อมต่อของคุณให้จัดการ fields ใหม่ได้อย่างเหมาะสม:

// ✅ ดี - ละเว้น fields ที่ไม่รู้จัก
const { id, amount, status } = charge;

// ❌ ไม่ดี - พังถ้ามี fields ใหม่เพิ่มมา
const charge = { id, amount, status }; // สมมติว่ามีแค่ fields เหล่านี้

แนวทางปฏิบัติที่ดีที่สุด​

1. ล็อกเวอร์ชัน API อย่างชัดเจน​

# ✅ ดี - เวอร์ชันชัดเจน
Omise.api_version = '2019-05-29'

# ❌ ไม่ดี - พึ่งพาค่าเริ่มต้นของบัญชี
Omise.api_version = nil  # ใช้ค่าเริ่มต้นของบัญชี

ทำไม:

  • ✅ ป้องกันการเปลี่ยนแปลงที่ไม่คาดคิด
  • ✅ เวอร์ชันชัดเจนในโค้ด
  • ✅ ทดสอบการอัปเกรดได้ง่าย
  • ✅ สม่ำเสมอข้าม environments

2. ใช้ Environment Variables​

// ✅ ดี - เวอร์ชันใน config
const omise = require('omise')({
  secretKey: process.env.OMISE_SECRET_KEY,
  omiseVersion: process.env.OMISE_API_VERSION || '2019-05-29'
});

ข้อดี:

  • ✅ เปลี่ยนได้ง่ายโดยไม่ต้อง deploy โค้ด
  • ✅ เวอร์ชันต่างกันต่อ environment
  • ✅ การตั้งค่าส่วนกลาง

3. ทดสอบการอัปเกรดเวอร์ชันอย่างละเอียด​

# Test suite สำหรับการอัปเกรดเวอร์ชัน
class TestAPIVersion2019(unittest.TestCase):
    def setUp(self):
        omise.api_version = '2019-05-29'

    def test_charge_creation(self):
        charge = omise.Charge.create(
            amount=100000,
            currency='thb',
            card=token
        )
        self.assertEqual(charge.amount, 100000)

    def test_source_creation(self):
        source = omise.Source.create(
            type='promptpay',
            amount=100000,
            currency='thb'
        )
        self.assertIsNotNone(source.scannable_code)

อ้างอิงด่วน​

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

2019-05-29

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

# ใน header
curl -H "Omise-Version: 2019-05-29" ...

# ใน Ruby
Omise.api_version = '2019-05-29'

# ใน Python
omise.api_version = '2019-05-29'

# ใน Node.js
omise = require('omise')({ omiseVersion: '2019-05-29' })

# ใน PHP
define('OMISE_API_VERSION', '2019-05-29');

# ใน Go
client.APIVersion = "2019-05-29"

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

YYYY-MM-DD (เช่น 2019-05-29)

Breaking Changes​

  • เฉพาะในเวอร์ชันใหม่
  • เวอร์ชันเก่ายังคงเสถียร
  • คุณควบคุมเวลาอัปเกรด
  • มีคู่มือ migration

Non-Breaking Changes​

  • อาจถูกเพิ่มในทุกเวอร์ชัน
  • fields, endpoints, ฟีเจอร์ใหม่
  • จัดการ fields ที่ไม่รู้จักอย่างเหมาะสม
  • สร้างโค้ดที่ forward-compatible

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

ถัดไป: เรียนรู้วิธีอยู่ภายในขีดจำกัด API และจัดการข้อผิดพลาด rate limit ใน Rate Limiting