Open APIs

Dear Contributors,

We have extended a Payment Management API to include Payment Plan as resource.

My End Point for paymentPlan resource would be like - /payment/v4/paymentPlan (similar to /payment/v4/payment)

Query is how to mention the version number of Payment Plan in resource URL ? like we mention it for Payment ?

Thanks

Abhinav Aggarwal

Hi Abhinav,

Yes, you can choose to follow the TMF way of representing the URL. TMF630 Part 1 document provide guidance on versioning.

However, please also see TMF666 Account Management API which has a paymentPlan sub-resource. TMFC029 (Payment Management Component Document) provides some additional clarity as well. 

To specify the version number for the paymentPlan resource in the URL, you can follow a similar pattern as you've used for the payment resource. If you are defining separate versions for different resources, or prefer a consistent approach across all resources, there are several options:
Option 1: Version the entire API (same version for all resources)
/payment/v4/paymentPlan
In this case, the version v4 applies to both payment and paymentPlan resources, meaning any changes made to the API would be versioned uniformly across all endpoints.
Option 2: Versioning specific to the paymentPlan resource
If you want to give the paymentPlan resource a different version number, you could do something like:
/payment/v4/paymentPlan/v1
This approach indicates that the paymentPlan resource is versioned separately from other resources like payment.
Option 3: Use paymentPlan version in the query parameters
You could also define the version number in the query parameters:
/payment/v4/paymentPlan?version=1
This gives flexibility to specify versioning at the resource level through query parameters.
Option 4: Combine major version with resource name
If you need to version the paymentPlan resource distinctly, you could separate the version in the resource path:
/payment/v4/paymentPlan-v1

The choice of versioning style depends on your API's design philosophy and whether you want consistent versioning for all resources or individual version control for specific resources like paymentPlan. If you're uncertain about the best approach for your API design, you can seek help from custom software development specialists https://tech-stack.com/services/custom-software-development to guide you in making the right decision.