<aside> 💡 Date: 2025-02-06

The new v3 API endpoints have been added, with several important differences compared to v2. Each version will be maintained separately, and the key differences between the existing v2 and the new v3 are outlined below.

1. API Path and Version Header Changes

1.1 Handling Invalid API Requests

1. If a request is made to an incorrect path (anything other than v2 or v3), the server will return a 400 Bad Request with the following error message:

   {
       "message": "Invalid API version path"
   }
   

2. If the version header does not match the path, the server will return a 400 Bad Request with the following error message:

   {
       "message": "Invalid API version header"
   }
   

3. If a v3 API key is used to access a v2 path, the server will return a 403 Forbidden with the following error message:

   {
       "message": "You do not have access to API version 'v2'"
   }
   

2. API-Specific Changes

2.1 Key Differences Between v2 and v3

2.2 Order APIs

• Endpoints:
  • POST /v3/orders (Order Registration)
  • PUT /v3/orders (Modify an Order)
• Updated Parameter Validation:
  • Affected fields:
    • ordererPhoneNo: Orderer’s Phone Number
    • ordererMobileNo: Orderer’s Mobile Number
    • receiverPhoneNo: Receiver’s Phone Number
    • receiverMobileNo: Receiver’s Mobile Number
  • Phone Number Format Requirement:

    • Must follow the E.164 format.

    • Requests with incorrect phone number formats will result in a 400 Bad Request with the following error message:

      {
          "message": "invalid phone number. please use E.164 format"
      }
      
      

3.3 Video iframe call API

• Endpoint: GET /v3/videos/{videoCode}/embed
• Changes:
  • The 205 Reset Content response code has been removed.
  • Successful responses will return 200 OK only.

3. 유의 사항

• Please ensure that each API call uses the correct path and version header corresponding to the respective API version.
• When migrating from v2 to v3, make sure to validate that phone numbers follow the E.164 format before making any requests related to the order APIs.
• If you have logic that expects a 205 Reset Content response in the video iframe API when migrating from v2 to v3, please note that the 205 Reset Content response is no longer supported. Update it to handle the 200 OK response instead. </aside>