Open APIs

Need support and guidance and reviewing the below and suggesting the best practices

TMF678 – Customer Bill Managament Api

1.           Get all bills for a customer with CRM Customer No & date range

GET {{baseUrl}}/customerBillManagement/v4/customerBill?filter=relatedParty.id=='32523424';billDate=ge=2024-01-01;billDate=le=2024-06-30

2.           Get all bills for multiple billing accounts with date range & state

GET {{baseUrl}}/customerBill?filter=billingAccount.id=in=('ACC-001','ACC-002');billDate>='2025-01-01';billDate<='2025-06-01';state=='new'

Response : 

Queries

• Is it allowed to use filter in the url?
• is the above syntax correct? can we use FIQL?
• is it allowed to fetch by multiple billing accounts?
• is it ok to use characteristic in response? there is no such field in the specifications? what is best way to implement such fields which are not available in SID schema?

------------------------------
Manudeep Bhandaru
OMANTEL
------------------------------

Hi Manudeep,

To your two points:

1. Yes - it is completely fine to use filter criteria in a GET to narrow the range of responses. The TMForum API Design Guidelines mention this. However I think you would achieve your example "customerBill?filter=billingAccount.id=in=('ACC-001','ACC-002')" as "customerBill?billingAccount.id=ACC-001&billingAccount.id=ACC-002".
   The design guidelines use a similar example of "GET /resourceInventoryManagement/logicalResource?id=42&id=44" - so retrieving a collection using multiple ids is fine.
   
2. For your date range example, I would probably try JSON-Path expression syntax which gives you operators (>, >=, != etc) and functions (min(), avg(), sum() etc). JSON-Path is mentioned as the defacto expression syntax in various places in the design guidelines.

Regarding your point about:

It is very much recognised that the TMF schemas present a generic framework that might have wide applicability to many use-cases, but if you want to add properties specific to your internal interactions (like your DISPUTEAMOUNT), you can always extend the TMF schemas. This is typically done by adding a new schema to the definitions section of the TMF swagger, called (say) CustomerBillExtended, looking a bit like this:

Then you can fiddle with the existing operations to accept and return a CustomerBillExtended rather than a CustomerBill. The resultant API will be compatible with the TMF original, and would still pass a TMF Conformance Test Kit (CTK), which would only test for mandatory properties from the original. It will ignore any additional properties.

------------------------------
Stephen Harrop
Principal Integration Architect
Vodafone Group
------------------------------