OAID - v1 and v2 Comparison
The OAID API has recently been updated, introducing several modifications to the API. In this blog, we break down the key differences to requesting and confirming an OAID between versions v1 and v2.
The yio team is actively working on updating the v2 documentation. The current documentation for v1 and v2 can be found below:
Comparison of Endpoints
Create OAID
Apart from the endpoint name changing from "Request OAID" to "Create OAID", its functionality remains consistent with the method used in v1.
Create OAID | v1 | v2 |
---|---|---|
Endpoint: | Request OAID | Create OAID |
Method: | POST |
POST |
HTTP Request: Create OAID
### Create new OAID code (v2)
POST https://api.oaid.at/v2/pip/codes/
Accept: application/json
Content-Type: application/json
Authorization: Bearer <access_token>
{"customer_reference": "loc01212-2442346"}
### Request new OAID code (v1)
POST https://api.oaid.at/v1/pip/codes/
Accept: application/json
Content-Type: application/json
Authorization: Bearer <access_token>
{"tenant": "ofaa.demo", "version": "v6"}
Confirm OAID
An OAID was confirmed in v1 through the PUT method "Confirm/Cancel OAID".
The parameter "token": "confirmed"
was required to provide in the request body for successful confirmation.
In v2, the OAID is confirmed with the PATCH method "Set OAID Attributes".
The token
parameter is set to confirmed
by default in the v2 update. This means OAID confirmation is implicit through any action with this method.
Confirm OAID | v1 | v2 |
---|---|---|
Endpoint: | Confirm/Cancel OAID | Set OAID Attributes |
Method: | PUT |
PATCH |
Minimal Request Body Requirement: |
{"token": "confirmed"} |
{ } |
HTTP Request: Confirm OAID
### Set OAID Attributes (v2)
PATCH https://api.oaid.at/v2/pip/codes/<oaid>/
Accept: application/json
Content-Type: application/json
Authorization: Bearer <access_token>
{"token": "confirmed"}
### Confirm/cancel OAID (v1)
PUT https://api.oaid.at/v1/pip/codes/<oaid>/token/
Accept: application/json
Content-Type: application/json
Authorization: Bearer <access_token>
{"token": "confirmed"}
Since "confirmed" is the default value for "token", replacing {"token": "confirmed"}
with { }
confirms the code as well!
### Set OAID Attributes (v2)
PATCH https://api.oaid.at/v2/pip/codes/<oaid>/
Accept: application/json
Content-Type: application/json
Authorization: Bearer <access_token>
{ }
Cancel OAID
Version v1 enabled the cancelation of an OAID with the same "Confirm/Cancel OAID" PUT method used to confirm an OAID. The status could be changed by setting the token in the Request Body to "canceled"
.
Once the OAID was canceled, the status could not be reversed, and the "canceled" status could be read with the "Read OAID" endpoint.
The 2nd version differs through the use of a DELETE method, "Cancel OAID". Compared to v1, this method entirely deletes the existence of the OAID, not permitting the status to be read afterward.
Cancel OAID | v1 | v2 |
---|---|---|
Endpoint: | Confirm/Cancel OAID | Cancel OAID |
Method: | PUT |
DELETE |
Request Body: | {"token": "canceled"} |
N/A |
HTTP Request: Cancel OAID
### Cancel OAID (v2)
DELETE https://api.oaid.at/v2/pip/codes/<oaid>/
Accept: application/json
Authorization: Bearer <access_token>
### Confirm/cancel OAID (v1)
PUT https://api.oaid.at/v1/pip/codes/<oaid>/token/
Accept: application/json
Content-Type: application/json
Authorization: Bearer <access_token>
{"token": "canceled"}