TM Forum Community

Hello guys, I'm getting very familiar with the topic of tmforums, I have a question that always happens to us. here you go.

What happens if I have an API, for example, that I need to net on a domain, for example, the tmf639 resource inventory.

My design api receives an array list and responds with an array list with more details.

Although my API is included in the TMF639 as an inventory, it does not adapt to the raw material they handle here.

Now the assembly of my request responds, I put it together following the guidelines they define.

but I need support on which path to use
Firstly it had /resource type post but this is used in the domain to create a resource.

So I have read several forums and it says to use verbs and that this would be a task.

My question is I have 2 examples

Post /resource/querySimcard
POST /resource/simcard/query

Although I still leave my api in the resource domain but now after /resource comes the issue, I don't know if it combines part of /resource/verb with a noun

or separate the noun and the verb like example 2.

The examples I saw still don't define it well, they give me a hand

It looks like you want to implement queries with TMF639. What you want to do is support a GET operation on the /resource collection. Simple queries may use attribute filtering with query parameters, as described in TMF630 Part 1; Chapter 4: Query Resources Patterns. Advanced queries may use JSON Path in the filter query parameter as described in TMF630 Part 6.

You seem to have an idea to invent your own query operations with a Task resource. This is something to be strictly avoided, however to answer your question, your first example would be a better choice than the second.

Hello guys, I'm getting very familiar with the topic of tmforums, I have a question that always happens to us. here you go.

What happens if I have an API, for example, that I need to net on a domain, for example, the tmf639 resource inventory.

My design api receives an array list and responds with an array list with more details.

Although my API is included in the TMF639 as an inventory, it does not adapt to the raw material they handle here.

Now the assembly of my request responds, I put it together following the guidelines they define.

but I need support on which path to use
Firstly it had /resource type post but this is used in the domain to create a resource.

So I have read several forums and it says to use verbs and that this would be a task.

My question is I have 2 examples

Post /resource/querySimcard
POST /resource/simcard/query

Although I still leave my api in the resource domain but now after /resource comes the issue, I don't know if it combines part of /resource/verb with a noun

or separate the noun and the verb like example 2.

The examples I saw still don't define it well, they give me a hand

Okay, thanks for responding, friend. Yes, indeed, my API needs to receive a list of SIM cards with their serial numbers, and then we must return the same list but with more details. Our API is powered by three backends to provide the details. Now, the company wants us to follow TMForum standards, which seems perfect to me. But we're running into this problem. Is it convenient to create tasks with the POST method, or what can we do to retrieve an array of, say, 100 items? Using GET doesn't seem very feasible. That's why I read about the task and thought about giving my API its own path. What do you recommend I do? Sorry, I'm new to TMForum.

That's why I posted two examples. I don't know if it's valid to use /resource as the base path. And then, as I mentioned, use mine /resource/querySimcardDetails. Here, I'll leave it inside /resource because a SIM card is an inventory. Now, is it possible to use /querySimcardDetails directly as the path? Just as if it were another operation within resource-management-inventory? This is what I mean by removing /resource and adding the path directly.

It looks like you want to implement queries with TMF639. What you want to do is support a GET operation on the /resource collection. Simple queries may use attribute filtering with query parameters, as described in TMF630 Part 1; Chapter 4: Query Resources Patterns. Advanced queries may use JSON Path in the filter query parameter as described in TMF630 Part 6.

You seem to have an idea to invent your own query operations with a Task resource. This is something to be strictly avoided, however to answer your question, your first example would be a better choice than the second.

Hello guys, I'm getting very familiar with the topic of tmforums, I have a question that always happens to us. here you go.

What happens if I have an API, for example, that I need to net on a domain, for example, the tmf639 resource inventory.

My design api receives an array list and responds with an array list with more details.

Although my API is included in the TMF639 as an inventory, it does not adapt to the raw material they handle here.

Now the assembly of my request responds, I put it together following the guidelines they define.

but I need support on which path to use
Firstly it had /resource type post but this is used in the domain to create a resource.

So I have read several forums and it says to use verbs and that this would be a task.

My question is I have 2 examples

Post /resource/querySimcard
POST /resource/simcard/query

Although I still leave my api in the resource domain but now after /resource comes the issue, I don't know if it combines part of /resource/verb with a noun

or separate the noun and the verb like example 2.

The examples I saw still don't define it well, they give me a hand

Brian,

If ICCID is a Characteristic you may use JSON Path to query the Resource Inventory for a match on Characteristic name and value:

    GET /resourceInventoryManagement/v4/resource?filter=resourceCharacteristic[?@.name=='ICCID' && @.value='8900000000000000001'] 

A GET of the Collection provides a response body which is an array of JSON objects of @type Resource, so it's quite normal for a query response to include multiple items. You may tailor your query to match a list of SIMs:

    GET /resourceInventoryManagement/v4/resource?filter=resourceCharacteristic[?@.name=='ICCID' && (@.value='8900000000000000001' || @.value='8900000000000000002' || @.value='8900000000000000003' || @.value='8900000000000000004' || @.value='8900000000000000005' || @.value='8900000000000000006' || @.value='8900000000000000007' || @.value='8900000000000000008' || @.value='8900000000000000009' || @.value='8900000000000000010')] 

Okay, thanks for responding, friend. Yes, indeed, my API needs to receive a list of SIM cards with their serial numbers, and then we must return the same list but with more details. Our API is powered by three backends to provide the details. Now, the company wants us to follow TMForum standards, which seems perfect to me. But we're running into this problem. Is it convenient to create tasks with the POST method, or what can we do to retrieve an array of, say, 100 items? Using GET doesn't seem very feasible. That's why I read about the task and thought about giving my API its own path. What do you recommend I do? Sorry, I'm new to TMForum.

That's why I posted two examples. I don't know if it's valid to use /resource as the base path. And then, as I mentioned, use mine /resource/querySimcardDetails. Here, I'll leave it inside /resource because a SIM card is an inventory. Now, is it possible to use /querySimcardDetails directly as the path? Just as if it were another operation within resource-management-inventory? This is what I mean by removing /resource and adding the path directly.

It looks like you want to implement queries with TMF639. What you want to do is support a GET operation on the /resource collection. Simple queries may use attribute filtering with query parameters, as described in TMF630 Part 1; Chapter 4: Query Resources Patterns. Advanced queries may use JSON Path in the filter query parameter as described in TMF630 Part 6.

You seem to have an idea to invent your own query operations with a Task resource. This is something to be strictly avoided, however to answer your question, your first example would be a better choice than the second.

Hello guys, I'm getting very familiar with the topic of tmforums, I have a question that always happens to us. here you go.

What happens if I have an API, for example, that I need to net on a domain, for example, the tmf639 resource inventory.

My design api receives an array list and responds with an array list with more details.

Although my API is included in the TMF639 as an inventory, it does not adapt to the raw material they handle here.

Now the assembly of my request responds, I put it together following the guidelines they define.

but I need support on which path to use
Firstly it had /resource type post but this is used in the domain to create a resource.

So I have read several forums and it says to use verbs and that this would be a task.

My question is I have 2 examples

Post /resource/querySimcard
POST /resource/simcard/query

Although I still leave my api in the resource domain but now after /resource comes the issue, I don't know if it combines part of /resource/verb with a noun

or separate the noun and the verb like example 2.

The examples I saw still don't define it well, they give me a hand

Thank you very much advance. It really is a good help.

Today they told me that they want to send 500 simcards, meaning iccid, plus one more value of their origin.

I think about taking the option of the task resource using the POST method. and use this path /resource/querySimcardDetails , i have the request and response in array list.

POST

request

[
  {
    "type": "SimCard",
    "serialNumber": "890000000000000001",
    "resourceCharacteristic": [
      {
        "name": "channel",
        "value": "AG",
      }
    ]
  },
  {
    "type": "SimCard",
    "serialNumber": "890000000000000002",
    "resourceCharacteristic": [
      {
        "name": "channel",
        "value": "OC",
      }
    ]
  }
]

response

[
  {
    "id": "RES-890000000000000002",
    "type": "SimCard",
    "serialNumber": "890000000000000002",
    "resourceCharacteristic": [
      {
        "name": "imsi",
        "value": "700000000000001"
      },
      {
        "name": "ki",
        "value": "abc123xyz"
      },
      {
        "name": "itemCode",
        "value": "PS11111"
      }
    ],
     "place": {
          "id": "PL-XI04DP00",
          "name": "XI04DP00"
        }
  },
  {
    "id": "RES-890000000000000001",
    "type": "SimCard",
    "serialNumber": "890000000000000001",
    "resourceCharacteristic": [
      {
        "name": "imsi",
        "value": "700000000000002"
      },
      {
        "name": "ki",
        "value": "def456uvw"
      },
      {
        "name": "itemCode",
        "value": "PS11111"
      }
    ],
     "place": {
          "id": "PL-XI04DP00",
          "name": "XI04DP00"
        }
  }
]

I do this since I send 500 items per parameter get no, if it is the most advisable in your example, an array of 10 is super valid and seems excellent to me, but for larger fields, that is, more than 10, it is preferable to use task or what do you think about it?

The api will only query it with 500 json objects.

------------------------------
brian molina
TO BE VERIFIED

Original Message:
Sent: Jun 02, 2025 13:53
From: Vance Shipley
Subject: standards for an api request list array and response array TMF639 resource invetory

Brian,

If ICCID is a Characteristic you may use JSON Path to query the Resource Inventory for a match on Characteristic name and value:

    GET /resourceInventoryManagement/v4/resource?filter=resourceCharacteristic[?@.name=='ICCID' && @.value='8900000000000000001'] 

A GET of the Collection provides a response body which is an array of JSON objects of @type Resource, so it's quite normal for a query response to include multiple items. You may tailor your query to match a list of SIMs:

    GET /resourceInventoryManagement/v4/resource?filter=resourceCharacteristic[?@.name=='ICCID' && (@.value='8900000000000000001' || @.value='8900000000000000002' || @.value='8900000000000000003' || @.value='8900000000000000004' || @.value='8900000000000000005' || @.value='8900000000000000006' || @.value='8900000000000000007' || @.value='8900000000000000008' || @.value='8900000000000000009' || @.value='8900000000000000010')] 

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: Jun 02, 2025 03:30
From: brian molina
Subject: standards for an api request list array and response array TMF639 resource invetory

Okay, thanks for responding, friend. Yes, indeed, my API needs to receive a list of SIM cards with their serial numbers, and then we must return the same list but with more details. Our API is powered by three backends to provide the details. Now, the company wants us to follow TMForum standards, which seems perfect to me. But we're running into this problem. Is it convenient to create tasks with the POST method, or what can we do to retrieve an array of, say, 100 items? Using GET doesn't seem very feasible. That's why I read about the task and thought about giving my API its own path. What do you recommend I do? Sorry, I'm new to TMForum.

That's why I posted two examples. I don't know if it's valid to use /resource as the base path. And then, as I mentioned, use mine /resource/querySimcardDetails. Here, I'll leave it inside /resource because a SIM card is an inventory. Now, is it possible to use /querySimcardDetails directly as the path? Just as if it were another operation within resource-management-inventory? This is what I mean by removing /resource and adding the path directly.

------------------------------
brian molina
TO BE VERIFIED

Original Message:
Sent: Jun 02, 2025 02:13
From: Vance Shipley
Subject: standards for an api request list array and response array TMF639 resource invetory

It looks like you want to implement queries with TMF639. What you want to do is support a GET operation on the /resource collection. Simple queries may use attribute filtering with query parameters, as described in TMF630 Part 1; Chapter 4: Query Resources Patterns. Advanced queries may use JSON Path in the filter query parameter as described in TMF630 Part 6.

You seem to have an idea to invent your own query operations with a Task resource. This is something to be strictly avoided, however to answer your question, your first example would be a better choice than the second.

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: May 29, 2025 15:17
From: brian molina
Subject: standards for an api request list array and response array TMF639 resource invetory

Hello guys, I'm getting very familiar with the topic of tmforums, I have a question that always happens to us. here you go.

What happens if I have an API, for example, that I need to net on a domain, for example, the tmf639 resource inventory.

My design api receives an array list and responds with an array list with more details.

Although my API is included in the TMF639 as an inventory, it does not adapt to the raw material they handle here.

Now the assembly of my request responds, I put it together following the guidelines they define.

but I need support on which path to use
Firstly it had /resource type post but this is used in the domain to create a resource.

So I have read several forums and it says to use verbs and that this would be a task.

My question is I have 2 examples

Post /resource/querySimcard
POST /resource/simcard/query

Although I still leave my api in the resource domain but now after /resource comes the issue, I don't know if it combines part of /resource/verb with a noun

or separate the noun and the verb like example 2.

The examples I saw still don't define it well, they give me a hand

#General

------------------------------
brian molina
TO BE VERIFIED
------------------------------

If you are going to claim support of TMF639 you need to first implement the standard Resource Inventory functionality. So you MUST implement this:

    GET /resourceInventoryManagement/v4/resource

The response MUST be a JSON array of objects, each having the mandatory attributes of a Resource which include id and href. If you intend to extend Resource, through polymorphism, you MUST also include @baseType, @type and @schemaLocation. If you will use the Characteristic pattern you should also include resourceSpecification.

{
    "id": "93ff2da1",
    "href": "/resourceInventoryManagement/v4/resource/93ff2da1",
    "@type": "SimCard",
    "@baseType": "LogicalResource",
    "@schemaLocation": "/schema/SimCard.schema.json",
    "resourceSpecification": {
        "id": "c75578fc",
        "href": "/resourceCatalog/v4/resourceSpecification/c75578fc",
        "name": "SimCard"
    },
    "resourceCharacteristic": []
}

Now having done this you have tethered your API to the TM Forum Open API program. Proprietary extensions MUST fit within the Open API data model by avoiding name clashes and including mandatory attributes, and should follow the patterns and practices of TMF630. If you implement a Task Resource for a specialized query the response body should be compatible with that of a GET operation.

Brian asks:
>  I do this since I send 500 items per parameter get no, if it is the most advisable in your example, an array of 10 is super valid and seems excellent to me, but for larger fields, that is, more than 10, it is preferable to use task or what do you think about it?

I would first, and foremost, implement the standard Open API.  A proprietary extension should be done out of desperation, but you would do that ALSO.

I took my JSON Path (TMF630 Part 6) example and extended it for 500 values with the resulting URL, after percent encoding, having 21633 characters. While this may seem unwieldy there is no size limit imposed on a URL by the RFCs and RFC9110 recommends that a minimum of 8000 octets be supported.

Your example however uses an extension attribute serialNumber rather than a Characteristic. This would allow the simpler query syntax of TMF630 Part 1:

    GET /resourceInventoryManagement/v4/resource?serialNumber=890000000000000001;890000000000000002

Expanding that for 500 values results in a URL of only 9954.

Note that there is an IETF draft for an HTTP QUERY method. If I were to invent something here I would, as Wayne Gretzky would say, "skate to where the puck is going to be". ;)

[Note: I do not speak for the TM Forum, this is merely one member's advice]

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: Jun 02, 2025 14:09
From: brian molina
Subject: standards for an api request list array and response array TMF639 resource invetory

Thank you very much advance. It really is a good help.

Today they told me that they want to send 500 simcards, meaning iccid, plus one more value of their origin.

I think about taking the option of the task resource using the POST method. and use this path /resource/querySimcardDetails , i have the request and response in array list.

POST

request

[
  {
    "type": "SimCard",
    "serialNumber": "890000000000000001",
    "resourceCharacteristic": [
      {
        "name": "channel",
        "value": "AG",
      }
    ]
  },
  {
    "type": "SimCard",
    "serialNumber": "890000000000000002",
    "resourceCharacteristic": [
      {
        "name": "channel",
        "value": "OC",
      }
    ]
  }
]

response

[
  {
    "id": "RES-890000000000000002",
    "type": "SimCard",
    "serialNumber": "890000000000000002",
    "resourceCharacteristic": [
      {
        "name": "imsi",
        "value": "700000000000001"
      },
      {
        "name": "ki",
        "value": "abc123xyz"
      },
      {
        "name": "itemCode",
        "value": "PS11111"
      }
    ],
     "place": {
          "id": "PL-XI04DP00",
          "name": "XI04DP00"
        }
  },
  {
    "id": "RES-890000000000000001",
    "type": "SimCard",
    "serialNumber": "890000000000000001",
    "resourceCharacteristic": [
      {
        "name": "imsi",
        "value": "700000000000002"
      },
      {
        "name": "ki",
        "value": "def456uvw"
      },
      {
        "name": "itemCode",
        "value": "PS11111"
      }
    ],
     "place": {
          "id": "PL-XI04DP00",
          "name": "XI04DP00"
        }
  }
]

I do this since I send 500 items per parameter get no, if it is the most advisable in your example, an array of 10 is super valid and seems excellent to me, but for larger fields, that is, more than 10, it is preferable to use task or what do you think about it?

The api will only query it with 500 json objects.

------------------------------
brian molina
TO BE VERIFIED

Original Message:
Sent: Jun 02, 2025 13:53
From: Vance Shipley
Subject: standards for an api request list array and response array TMF639 resource invetory

Brian,

If ICCID is a Characteristic you may use JSON Path to query the Resource Inventory for a match on Characteristic name and value:

    GET /resourceInventoryManagement/v4/resource?filter=resourceCharacteristic[?@.name=='ICCID' && @.value='8900000000000000001'] 

A GET of the Collection provides a response body which is an array of JSON objects of @type Resource, so it's quite normal for a query response to include multiple items. You may tailor your query to match a list of SIMs:

    GET /resourceInventoryManagement/v4/resource?filter=resourceCharacteristic[?@.name=='ICCID' && (@.value='8900000000000000001' || @.value='8900000000000000002' || @.value='8900000000000000003' || @.value='8900000000000000004' || @.value='8900000000000000005' || @.value='8900000000000000006' || @.value='8900000000000000007' || @.value='8900000000000000008' || @.value='8900000000000000009' || @.value='8900000000000000010')] 

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: Jun 02, 2025 03:30
From: brian molina
Subject: standards for an api request list array and response array TMF639 resource invetory

Okay, thanks for responding, friend. Yes, indeed, my API needs to receive a list of SIM cards with their serial numbers, and then we must return the same list but with more details. Our API is powered by three backends to provide the details. Now, the company wants us to follow TMForum standards, which seems perfect to me. But we're running into this problem. Is it convenient to create tasks with the POST method, or what can we do to retrieve an array of, say, 100 items? Using GET doesn't seem very feasible. That's why I read about the task and thought about giving my API its own path. What do you recommend I do? Sorry, I'm new to TMForum.

That's why I posted two examples. I don't know if it's valid to use /resource as the base path. And then, as I mentioned, use mine /resource/querySimcardDetails. Here, I'll leave it inside /resource because a SIM card is an inventory. Now, is it possible to use /querySimcardDetails directly as the path? Just as if it were another operation within resource-management-inventory? This is what I mean by removing /resource and adding the path directly.

------------------------------
brian molina
TO BE VERIFIED

Original Message:
Sent: Jun 02, 2025 02:13
From: Vance Shipley
Subject: standards for an api request list array and response array TMF639 resource invetory

It looks like you want to implement queries with TMF639. What you want to do is support a GET operation on the /resource collection. Simple queries may use attribute filtering with query parameters, as described in TMF630 Part 1; Chapter 4: Query Resources Patterns. Advanced queries may use JSON Path in the filter query parameter as described in TMF630 Part 6.

You seem to have an idea to invent your own query operations with a Task resource. This is something to be strictly avoided, however to answer your question, your first example would be a better choice than the second.

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: May 29, 2025 15:17
From: brian molina
Subject: standards for an api request list array and response array TMF639 resource invetory

Hello guys, I'm getting very familiar with the topic of tmforums, I have a question that always happens to us. here you go.

What happens if I have an API, for example, that I need to net on a domain, for example, the tmf639 resource inventory.

My design api receives an array list and responds with an array list with more details.

Although my API is included in the TMF639 as an inventory, it does not adapt to the raw material they handle here.

Now the assembly of my request responds, I put it together following the guidelines they define.

but I need support on which path to use
Firstly it had /resource type post but this is used in the domain to create a resource.

So I have read several forums and it says to use verbs and that this would be a task.

My question is I have 2 examples

Post /resource/querySimcard
POST /resource/simcard/query

Although I still leave my api in the resource domain but now after /resource comes the issue, I don't know if it combines part of /resource/verb with a noun

or separate the noun and the verb like example 2.

The examples I saw still don't define it well, they give me a hand

#General

------------------------------
brian molina
TO BE VERIFIED
------------------------------

Thanks Vance for responding.

I have two questions:

1. The company wants to implement APIs in tmforums. Remember how I mentioned that the get
GET /resourceInventoryManagement/v4/resource?serialNumber= 890000000000000001;890000000000000002
will not only pass serialNumber, but there are also other fields, for example, channel. With this additional field to the get, knowing that the get query will exceed 8000. So, how would I pass these fields? I understand there are no limits for this.
I really like your example according to 630 part 1:

Alternatively, the following expression [{attributeName}={attributeValue},\{attributeValue
}*] is also supported. ORING can also be explicit using ";" Many times
[{attributename}={attributevalue};{attributevalue}*]

Doing this example, the following would be a get:
GET /resourceInventoryManagement/v4/resource?serialNumber=890000000000000001;89000000000000002&channel=oc;ag

The company is more oriented toward this type of array of more than 100 items being passed per post.
However, it's a bit difficult to adapt to both company policies and tmforums, hahahahaha. Sorry.

With an urgency point, I could implement the resources task with the post method and pass my data via request ?. For example:

POST /resource/querySimCardDetail
Request:
[
{
"type": "SIM Card",
"serial number": "8934071234567890123",
"resource characteristic": [
{
"name": "channel",
"value": "AG",
}
]
},
{
"type": "SIM Card",
"serial number": "8934071234567890456",
"resource characteristic": [
{
"name": "channel",
"value": "OC",
}
]
}]

my second question:

this response that you put

{ 
"id": "93ff2da1", 
"href": "/resourceInventoryManagement/v4/resource/93ff2da1", 
"@type": "SimCard", 
"@baseType": "LogicalResource", 
"@schemaLocation": "/schema/SimCard.schema.json", 
"resourceSpecification": { 
"id": "c75578fc", 
"href": "/resourceCatalog/v4/resourceSpecification/c75578fc", 
"name": "SimCard" 
}, 
"resourceCharacteristic": []
}

I see the href field as mandatory with this value

/resourceInventoryManagement/v4/resource/93ff2da1

well here I refer for example to the id of the simcard itself, but if not I still have that get href implemented. What would I do in that case?

As I mentioned, my API will just use this TMF639 for the first time, hahaha.
And we only need it (for now)
to send a list of SIM cards, receive them, go through three backends, obtain additional information, and return the same list of SIM cards but with more details, such as KI, PUK, etc.

So, if I don't have that href implemented, do I have to implement it? Or what do I do in these cases?

In this case, I'm using polymorphism to use the serialNumber field, which is the ICCID.
So, do I also have to send these fields, baseType and schemaLocation, as required?

Finally, you mention: you use resourceCharacteristic, so I should use resourceSpecification.

I didn't know this. Is it necessary to tell the client the specification of that characteristic?

And here I have another question.

"resourceSpecification": {
"id": "c75578fc",
"href": "/resourceCatalog/v4/resourceSpecification/c75578fc",
"name": "SimCard"
}

If I don't have the ResourceCatalog API implemented yet, then I need to send this object.

What do you recommend?

I know there are a lot of questions. Sorry, I've just joined tmforums and I'm getting some context.

If you are going to claim support of TMF639 you need to first implement the standard Resource Inventory functionality. So you MUST implement this:

    GET /resourceInventoryManagement/v4/resource

The response MUST be a JSON array of objects, each having the mandatory attributes of a Resource which include id and href. If you intend to extend Resource, through polymorphism, you MUST also include @baseType, @type and @schemaLocation. If you will use the Characteristic pattern you should also include resourceSpecification.

{
    "id": "93ff2da1",
    "href": "/resourceInventoryManagement/v4/resource/93ff2da1",
    "@type": "SimCard",
    "@baseType": "LogicalResource",
    "@schemaLocation": "/schema/SimCard.schema.json",
    "resourceSpecification": {
        "id": "c75578fc",
        "href": "/resourceCatalog/v4/resourceSpecification/c75578fc",
        "name": "SimCard"
    },
    "resourceCharacteristic": []
}

Now having done this you have tethered your API to the TM Forum Open API program. Proprietary extensions MUST fit within the Open API data model by avoiding name clashes and including mandatory attributes, and should follow the patterns and practices of TMF630. If you implement a Task Resource for a specialized query the response body should be compatible with that of a GET operation.

Brian asks:
>  I do this since I send 500 items per parameter get no, if it is the most advisable in your example, an array of 10 is super valid and seems excellent to me, but for larger fields, that is, more than 10, it is preferable to use task or what do you think about it?

I would first, and foremost, implement the standard Open API.  A proprietary extension should be done out of desperation, but you would do that ALSO.

I took my JSON Path (TMF630 Part 6) example and extended it for 500 values with the resulting URL, after percent encoding, having 21633 characters. While this may seem unwieldy there is no size limit imposed on a URL by the RFCs and RFC9110 recommends that a minimum of 8000 octets be supported.

Your example however uses an extension attribute serialNumber rather than a Characteristic. This would allow the simpler query syntax of TMF630 Part 1:

    GET /resourceInventoryManagement/v4/resource?serialNumber=890000000000000001;890000000000000002

Expanding that for 500 values results in a URL of only 9954.

Note that there is an IETF draft for an HTTP QUERY method. If I were to invent something here I would, as Wayne Gretzky would say, "skate to where the puck is going to be". ;)

[Note: I do not speak for the TM Forum, this is merely one member's advice]

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: Jun 02, 2025 14:09
From: brian molina
Subject: standards for an api request list array and response array TMF639 resource invetory

Thank you very much advance. It really is a good help.

Today they told me that they want to send 500 simcards, meaning iccid, plus one more value of their origin.

I think about taking the option of the task resource using the POST method. and use this path /resource/querySimcardDetails , i have the request and response in array list.

POST

request

[
  {
    "type": "SimCard",
    "serialNumber": "890000000000000001",
    "resourceCharacteristic": [
      {
        "name": "channel",
        "value": "AG",
      }
    ]
  },
  {
    "type": "SimCard",
    "serialNumber": "890000000000000002",
    "resourceCharacteristic": [
      {
        "name": "channel",
        "value": "OC",
      }
    ]
  }
]

response

[
  {
    "id": "RES-890000000000000002",
    "type": "SimCard",
    "serialNumber": "890000000000000002",
    "resourceCharacteristic": [
      {
        "name": "imsi",
        "value": "700000000000001"
      },
      {
        "name": "ki",
        "value": "abc123xyz"
      },
      {
        "name": "itemCode",
        "value": "PS11111"
      }
    ],
     "place": {
          "id": "PL-XI04DP00",
          "name": "XI04DP00"
        }
  },
  {
    "id": "RES-890000000000000001",
    "type": "SimCard",
    "serialNumber": "890000000000000001",
    "resourceCharacteristic": [
      {
        "name": "imsi",
        "value": "700000000000002"
      },
      {
        "name": "ki",
        "value": "def456uvw"
      },
      {
        "name": "itemCode",
        "value": "PS11111"
      }
    ],
     "place": {
          "id": "PL-XI04DP00",
          "name": "XI04DP00"
        }
  }
]

I do this since I send 500 items per parameter get no, if it is the most advisable in your example, an array of 10 is super valid and seems excellent to me, but for larger fields, that is, more than 10, it is preferable to use task or what do you think about it?

The api will only query it with 500 json objects.

------------------------------
brian molina
TO BE VERIFIED

Original Message:
Sent: Jun 02, 2025 13:53
From: Vance Shipley
Subject: standards for an api request list array and response array TMF639 resource invetory

Brian,

If ICCID is a Characteristic you may use JSON Path to query the Resource Inventory for a match on Characteristic name and value:

    GET /resourceInventoryManagement/v4/resource?filter=resourceCharacteristic[?@.name=='ICCID' && @.value='8900000000000000001'] 

A GET of the Collection provides a response body which is an array of JSON objects of @type Resource, so it's quite normal for a query response to include multiple items. You may tailor your query to match a list of SIMs:

    GET /resourceInventoryManagement/v4/resource?filter=resourceCharacteristic[?@.name=='ICCID' && (@.value='8900000000000000001' || @.value='8900000000000000002' || @.value='8900000000000000003' || @.value='8900000000000000004' || @.value='8900000000000000005' || @.value='8900000000000000006' || @.value='8900000000000000007' || @.value='8900000000000000008' || @.value='8900000000000000009' || @.value='8900000000000000010')] 

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: Jun 02, 2025 03:30
From: brian molina
Subject: standards for an api request list array and response array TMF639 resource invetory

Okay, thanks for responding, friend. Yes, indeed, my API needs to receive a list of SIM cards with their serial numbers, and then we must return the same list but with more details. Our API is powered by three backends to provide the details. Now, the company wants us to follow TMForum standards, which seems perfect to me. But we're running into this problem. Is it convenient to create tasks with the POST method, or what can we do to retrieve an array of, say, 100 items? Using GET doesn't seem very feasible. That's why I read about the task and thought about giving my API its own path. What do you recommend I do? Sorry, I'm new to TMForum.

That's why I posted two examples. I don't know if it's valid to use /resource as the base path. And then, as I mentioned, use mine /resource/querySimcardDetails. Here, I'll leave it inside /resource because a SIM card is an inventory. Now, is it possible to use /querySimcardDetails directly as the path? Just as if it were another operation within resource-management-inventory? This is what I mean by removing /resource and adding the path directly.

------------------------------
brian molina
TO BE VERIFIED

Original Message:
Sent: Jun 02, 2025 02:13
From: Vance Shipley
Subject: standards for an api request list array and response array TMF639 resource invetory

It looks like you want to implement queries with TMF639. What you want to do is support a GET operation on the /resource collection. Simple queries may use attribute filtering with query parameters, as described in TMF630 Part 1; Chapter 4: Query Resources Patterns. Advanced queries may use JSON Path in the filter query parameter as described in TMF630 Part 6.

You seem to have an idea to invent your own query operations with a Task resource. This is something to be strictly avoided, however to answer your question, your first example would be a better choice than the second.

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: May 29, 2025 15:17
From: brian molina
Subject: standards for an api request list array and response array TMF639 resource invetory

Hello guys, I'm getting very familiar with the topic of tmforums, I have a question that always happens to us. here you go.

What happens if I have an API, for example, that I need to net on a domain, for example, the tmf639 resource inventory.

My design api receives an array list and responds with an array list with more details.

Although my API is included in the TMF639 as an inventory, it does not adapt to the raw material they handle here.

Now the assembly of my request responds, I put it together following the guidelines they define.

but I need support on which path to use
Firstly it had /resource type post but this is used in the domain to create a resource.

So I have read several forums and it says to use verbs and that this would be a task.

My question is I have 2 examples

Post /resource/querySimcard
POST /resource/simcard/query

Although I still leave my api in the resource domain but now after /resource comes the issue, I don't know if it combines part of /resource/verb with a noun

or separate the noun and the verb like example 2.

The examples I saw still don't define it well, they give me a hand

#General

------------------------------
brian molina
TO BE VERIFIED
------------------------------

Q1) Multiple query parameters use AND logic. If you are querying on ICCID you are very specifically selecting an item, so adding another match seems irrelevant. You don't reuse ICCIDs across channels do you?  Now maybe communicating the channel makes the query more efficient, so you do you.

Q2) In a POST to a collection (i.e. /resource) to create an item you must NOT include id and href, however they are mandatory in a response (the index value id is generated by the API producer). The TMF630 recommendation is to NOT use "business identities" as the value of id, however it is often quite tempting to ignore that for practical implementation considerations. The value of id is opaque so how you generate it is your business as the API producer.

A ResourceSpecification is how we define the names and potential value types and constraints for resourceCharacteristics in a Resource instance. You really must provide that definition to document how to use your your API. If you aren't producing TMF634 Resource Catalog API as part of your solution you should at least provide a JSON object (@type ResourceSpecification) which can be inserted in someone else's Catalog.

Thanks Vance for responding.

I have two questions:

1. The company wants to implement APIs in tmforums. Remember how I mentioned that the get
GET /resourceInventoryManagement/v4/resource?serialNumber= 890000000000000001;890000000000000002
will not only pass serialNumber, but there are also other fields, for example, channel. With this additional field to the get, knowing that the get query will exceed 8000. So, how would I pass these fields? I understand there are no limits for this.
I really like your example according to 630 part 1:

Alternatively, the following expression [{attributeName}={attributeValue},\{attributeValue
}*] is also supported. ORING can also be explicit using ";" Many times
[{attributename}={attributevalue};{attributevalue}*]

Doing this example, the following would be a get:
GET /resourceInventoryManagement/v4/resource?serialNumber=890000000000000001;89000000000000002&channel=oc;ag

The company is more oriented toward this type of array of more than 100 items being passed per post.
However, it's a bit difficult to adapt to both company policies and tmforums, hahahahaha. Sorry.

With an urgency point, I could implement the resources task with the post method and pass my data via request ?. For example:

POST /resource/querySimCardDetail
Request:
[
{
"type": "SIM Card",
"serial number": "8934071234567890123",
"resource characteristic": [
{
"name": "channel",
"value": "AG",
}
]
},
{
"type": "SIM Card",
"serial number": "8934071234567890456",
"resource characteristic": [
{
"name": "channel",
"value": "OC",
}
]
}]

my second question:

this response that you put

{ 
"id": "93ff2da1", 
"href": "/resourceInventoryManagement/v4/resource/93ff2da1", 
"@type": "SimCard", 
"@baseType": "LogicalResource", 
"@schemaLocation": "/schema/SimCard.schema.json", 
"resourceSpecification": { 
"id": "c75578fc", 
"href": "/resourceCatalog/v4/resourceSpecification/c75578fc", 
"name": "SimCard" 
}, 
"resourceCharacteristic": []
}

I see the href field as mandatory with this value

/resourceInventoryManagement/v4/resource/93ff2da1

well here I refer for example to the id of the simcard itself, but if not I still have that get href implemented. What would I do in that case?

As I mentioned, my API will just use this TMF639 for the first time, hahaha.
And we only need it (for now)
to send a list of SIM cards, receive them, go through three backends, obtain additional information, and return the same list of SIM cards but with more details, such as KI, PUK, etc.

So, if I don't have that href implemented, do I have to implement it? Or what do I do in these cases?

In this case, I'm using polymorphism to use the serialNumber field, which is the ICCID.
So, do I also have to send these fields, baseType and schemaLocation, as required?

Finally, you mention: you use resourceCharacteristic, so I should use resourceSpecification.

I didn't know this. Is it necessary to tell the client the specification of that characteristic?

And here I have another question.

"resourceSpecification": {
"id": "c75578fc",
"href": "/resourceCatalog/v4/resourceSpecification/c75578fc",
"name": "SimCard"
}

If I don't have the ResourceCatalog API implemented yet, then I need to send this object.

What do you recommend?

I know there are a lot of questions. Sorry, I've just joined tmforums and I'm getting some context.

If you are going to claim support of TMF639 you need to first implement the standard Resource Inventory functionality. So you MUST implement this:

    GET /resourceInventoryManagement/v4/resource

The response MUST be a JSON array of objects, each having the mandatory attributes of a Resource which include id and href. If you intend to extend Resource, through polymorphism, you MUST also include @baseType, @type and @schemaLocation. If you will use the Characteristic pattern you should also include resourceSpecification.

{
    "id": "93ff2da1",
    "href": "/resourceInventoryManagement/v4/resource/93ff2da1",
    "@type": "SimCard",
    "@baseType": "LogicalResource",
    "@schemaLocation": "/schema/SimCard.schema.json",
    "resourceSpecification": {
        "id": "c75578fc",
        "href": "/resourceCatalog/v4/resourceSpecification/c75578fc",
        "name": "SimCard"
    },
    "resourceCharacteristic": []
}

Now having done this you have tethered your API to the TM Forum Open API program. Proprietary extensions MUST fit within the Open API data model by avoiding name clashes and including mandatory attributes, and should follow the patterns and practices of TMF630. If you implement a Task Resource for a specialized query the response body should be compatible with that of a GET operation.

Brian asks:
>  I do this since I send 500 items per parameter get no, if it is the most advisable in your example, an array of 10 is super valid and seems excellent to me, but for larger fields, that is, more than 10, it is preferable to use task or what do you think about it?

I would first, and foremost, implement the standard Open API.  A proprietary extension should be done out of desperation, but you would do that ALSO.

I took my JSON Path (TMF630 Part 6) example and extended it for 500 values with the resulting URL, after percent encoding, having 21633 characters. While this may seem unwieldy there is no size limit imposed on a URL by the RFCs and RFC9110 recommends that a minimum of 8000 octets be supported.

Your example however uses an extension attribute serialNumber rather than a Characteristic. This would allow the simpler query syntax of TMF630 Part 1:

    GET /resourceInventoryManagement/v4/resource?serialNumber=890000000000000001;890000000000000002

Expanding that for 500 values results in a URL of only 9954.

Note that there is an IETF draft for an HTTP QUERY method. If I were to invent something here I would, as Wayne Gretzky would say, "skate to where the puck is going to be". ;)

[Note: I do not speak for the TM Forum, this is merely one member's advice]

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: Jun 02, 2025 14:09
From: brian molina
Subject: standards for an api request list array and response array TMF639 resource invetory

Thank you very much advance. It really is a good help.

Today they told me that they want to send 500 simcards, meaning iccid, plus one more value of their origin.

I think about taking the option of the task resource using the POST method. and use this path /resource/querySimcardDetails , i have the request and response in array list.

POST

request

[
  {
    "type": "SimCard",
    "serialNumber": "890000000000000001",
    "resourceCharacteristic": [
      {
        "name": "channel",
        "value": "AG",
      }
    ]
  },
  {
    "type": "SimCard",
    "serialNumber": "890000000000000002",
    "resourceCharacteristic": [
      {
        "name": "channel",
        "value": "OC",
      }
    ]
  }
]

response

[
  {
    "id": "RES-890000000000000002",
    "type": "SimCard",
    "serialNumber": "890000000000000002",
    "resourceCharacteristic": [
      {
        "name": "imsi",
        "value": "700000000000001"
      },
      {
        "name": "ki",
        "value": "abc123xyz"
      },
      {
        "name": "itemCode",
        "value": "PS11111"
      }
    ],
     "place": {
          "id": "PL-XI04DP00",
          "name": "XI04DP00"
        }
  },
  {
    "id": "RES-890000000000000001",
    "type": "SimCard",
    "serialNumber": "890000000000000001",
    "resourceCharacteristic": [
      {
        "name": "imsi",
        "value": "700000000000002"
      },
      {
        "name": "ki",
        "value": "def456uvw"
      },
      {
        "name": "itemCode",
        "value": "PS11111"
      }
    ],
     "place": {
          "id": "PL-XI04DP00",
          "name": "XI04DP00"
        }
  }
]

I do this since I send 500 items per parameter get no, if it is the most advisable in your example, an array of 10 is super valid and seems excellent to me, but for larger fields, that is, more than 10, it is preferable to use task or what do you think about it?

The api will only query it with 500 json objects.

------------------------------
brian molina
TO BE VERIFIED

Original Message:
Sent: Jun 02, 2025 13:53
From: Vance Shipley
Subject: standards for an api request list array and response array TMF639 resource invetory

Brian,

If ICCID is a Characteristic you may use JSON Path to query the Resource Inventory for a match on Characteristic name and value:

    GET /resourceInventoryManagement/v4/resource?filter=resourceCharacteristic[?@.name=='ICCID' && @.value='8900000000000000001'] 

A GET of the Collection provides a response body which is an array of JSON objects of @type Resource, so it's quite normal for a query response to include multiple items. You may tailor your query to match a list of SIMs:

    GET /resourceInventoryManagement/v4/resource?filter=resourceCharacteristic[?@.name=='ICCID' && (@.value='8900000000000000001' || @.value='8900000000000000002' || @.value='8900000000000000003' || @.value='8900000000000000004' || @.value='8900000000000000005' || @.value='8900000000000000006' || @.value='8900000000000000007' || @.value='8900000000000000008' || @.value='8900000000000000009' || @.value='8900000000000000010')] 

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: Jun 02, 2025 03:30
From: brian molina
Subject: standards for an api request list array and response array TMF639 resource invetory

Okay, thanks for responding, friend. Yes, indeed, my API needs to receive a list of SIM cards with their serial numbers, and then we must return the same list but with more details. Our API is powered by three backends to provide the details. Now, the company wants us to follow TMForum standards, which seems perfect to me. But we're running into this problem. Is it convenient to create tasks with the POST method, or what can we do to retrieve an array of, say, 100 items? Using GET doesn't seem very feasible. That's why I read about the task and thought about giving my API its own path. What do you recommend I do? Sorry, I'm new to TMForum.

That's why I posted two examples. I don't know if it's valid to use /resource as the base path. And then, as I mentioned, use mine /resource/querySimcardDetails. Here, I'll leave it inside /resource because a SIM card is an inventory. Now, is it possible to use /querySimcardDetails directly as the path? Just as if it were another operation within resource-management-inventory? This is what I mean by removing /resource and adding the path directly.

------------------------------
brian molina
TO BE VERIFIED

Original Message:
Sent: Jun 02, 2025 02:13
From: Vance Shipley
Subject: standards for an api request list array and response array TMF639 resource invetory

It looks like you want to implement queries with TMF639. What you want to do is support a GET operation on the /resource collection. Simple queries may use attribute filtering with query parameters, as described in TMF630 Part 1; Chapter 4: Query Resources Patterns. Advanced queries may use JSON Path in the filter query parameter as described in TMF630 Part 6.

You seem to have an idea to invent your own query operations with a Task resource. This is something to be strictly avoided, however to answer your question, your first example would be a better choice than the second.

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: May 29, 2025 15:17
From: brian molina
Subject: standards for an api request list array and response array TMF639 resource invetory

Hello guys, I'm getting very familiar with the topic of tmforums, I have a question that always happens to us. here you go.

What happens if I have an API, for example, that I need to net on a domain, for example, the tmf639 resource inventory.

My design api receives an array list and responds with an array list with more details.

Although my API is included in the TMF639 as an inventory, it does not adapt to the raw material they handle here.

Now the assembly of my request responds, I put it together following the guidelines they define.

but I need support on which path to use
Firstly it had /resource type post but this is used in the domain to create a resource.

So I have read several forums and it says to use verbs and that this would be a task.

My question is I have 2 examples

Post /resource/querySimcard
POST /resource/simcard/query

Although I still leave my api in the resource domain but now after /resource comes the issue, I don't know if it combines part of /resource/verb with a noun

or separate the noun and the verb like example 2.

The examples I saw still don't define it well, they give me a hand

#General

------------------------------
brian molina
TO BE VERIFIED
------------------------------

Okay, thanks, Vance.

If I received a list of 500 SIM cards, each with an assigned channel, is this mandatory to determine which SIM cards go to backend 1 or backend 2 depending on the channel. Then I go to backend 3 to obtain more data via the SIM card.

So, sorry to insist. This is very dedicated to SIM cards, hence my purpose of using a task resource. As I mentioned, and as I mentioned, the company won't allow me to send a lot of data via GET.

So, what could I do by joining the resourceTask, as I mentioned?
POST /resource/querySimCardDetail
with my request?

Now, in the response of this API, if I have to specify the resourceSpecification, how would the output look? Give me an example.

Q1) Multiple query parameters use AND logic. If you are querying on ICCID you are very specifically selecting an item, so adding another match seems irrelevant. You don't reuse ICCIDs across channels do you?  Now maybe communicating the channel makes the query more efficient, so you do you.

Q2) In a POST to a collection (i.e. /resource) to create an item you must NOT include id and href, however they are mandatory in a response (the index value id is generated by the API producer). The TMF630 recommendation is to NOT use "business identities" as the value of id, however it is often quite tempting to ignore that for practical implementation considerations. The value of id is opaque so how you generate it is your business as the API producer.

A ResourceSpecification is how we define the names and potential value types and constraints for resourceCharacteristics in a Resource instance. You really must provide that definition to document how to use your your API. If you aren't producing TMF634 Resource Catalog API as part of your solution you should at least provide a JSON object (@type ResourceSpecification) which can be inserted in someone else's Catalog.

Thanks Vance for responding.

I have two questions:

1. The company wants to implement APIs in tmforums. Remember how I mentioned that the get
GET /resourceInventoryManagement/v4/resource?serialNumber= 890000000000000001;890000000000000002
will not only pass serialNumber, but there are also other fields, for example, channel. With this additional field to the get, knowing that the get query will exceed 8000. So, how would I pass these fields? I understand there are no limits for this.
I really like your example according to 630 part 1:

Alternatively, the following expression [{attributeName}={attributeValue},\{attributeValue
}*] is also supported. ORING can also be explicit using ";" Many times
[{attributename}={attributevalue};{attributevalue}*]

Doing this example, the following would be a get:
GET /resourceInventoryManagement/v4/resource?serialNumber=890000000000000001;89000000000000002&channel=oc;ag

The company is more oriented toward this type of array of more than 100 items being passed per post.
However, it's a bit difficult to adapt to both company policies and tmforums, hahahahaha. Sorry.

With an urgency point, I could implement the resources task with the post method and pass my data via request ?. For example:

POST /resource/querySimCardDetail
Request:
[
{
"type": "SIM Card",
"serial number": "8934071234567890123",
"resource characteristic": [
{
"name": "channel",
"value": "AG",
}
]
},
{
"type": "SIM Card",
"serial number": "8934071234567890456",
"resource characteristic": [
{
"name": "channel",
"value": "OC",
}
]
}]

my second question:

this response that you put

{ 
"id": "93ff2da1", 
"href": "/resourceInventoryManagement/v4/resource/93ff2da1", 
"@type": "SimCard", 
"@baseType": "LogicalResource", 
"@schemaLocation": "/schema/SimCard.schema.json", 
"resourceSpecification": { 
"id": "c75578fc", 
"href": "/resourceCatalog/v4/resourceSpecification/c75578fc", 
"name": "SimCard" 
}, 
"resourceCharacteristic": []
}

I see the href field as mandatory with this value

/resourceInventoryManagement/v4/resource/93ff2da1

well here I refer for example to the id of the simcard itself, but if not I still have that get href implemented. What would I do in that case?

As I mentioned, my API will just use this TMF639 for the first time, hahaha.
And we only need it (for now)
to send a list of SIM cards, receive them, go through three backends, obtain additional information, and return the same list of SIM cards but with more details, such as KI, PUK, etc.

So, if I don't have that href implemented, do I have to implement it? Or what do I do in these cases?

In this case, I'm using polymorphism to use the serialNumber field, which is the ICCID.
So, do I also have to send these fields, baseType and schemaLocation, as required?

Finally, you mention: you use resourceCharacteristic, so I should use resourceSpecification.

I didn't know this. Is it necessary to tell the client the specification of that characteristic?

And here I have another question.

"resourceSpecification": {
"id": "c75578fc",
"href": "/resourceCatalog/v4/resourceSpecification/c75578fc",
"name": "SimCard"
}

If I don't have the ResourceCatalog API implemented yet, then I need to send this object.

What do you recommend?

I know there are a lot of questions. Sorry, I've just joined tmforums and I'm getting some context.

If you are going to claim support of TMF639 you need to first implement the standard Resource Inventory functionality. So you MUST implement this:

    GET /resourceInventoryManagement/v4/resource

The response MUST be a JSON array of objects, each having the mandatory attributes of a Resource which include id and href. If you intend to extend Resource, through polymorphism, you MUST also include @baseType, @type and @schemaLocation. If you will use the Characteristic pattern you should also include resourceSpecification.

{
    "id": "93ff2da1",
    "href": "/resourceInventoryManagement/v4/resource/93ff2da1",
    "@type": "SimCard",
    "@baseType": "LogicalResource",
    "@schemaLocation": "/schema/SimCard.schema.json",
    "resourceSpecification": {
        "id": "c75578fc",
        "href": "/resourceCatalog/v4/resourceSpecification/c75578fc",
        "name": "SimCard"
    },
    "resourceCharacteristic": []
}

Now having done this you have tethered your API to the TM Forum Open API program. Proprietary extensions MUST fit within the Open API data model by avoiding name clashes and including mandatory attributes, and should follow the patterns and practices of TMF630. If you implement a Task Resource for a specialized query the response body should be compatible with that of a GET operation.

Brian asks:
>  I do this since I send 500 items per parameter get no, if it is the most advisable in your example, an array of 10 is super valid and seems excellent to me, but for larger fields, that is, more than 10, it is preferable to use task or what do you think about it?

I would first, and foremost, implement the standard Open API.  A proprietary extension should be done out of desperation, but you would do that ALSO.

I took my JSON Path (TMF630 Part 6) example and extended it for 500 values with the resulting URL, after percent encoding, having 21633 characters. While this may seem unwieldy there is no size limit imposed on a URL by the RFCs and RFC9110 recommends that a minimum of 8000 octets be supported.

Your example however uses an extension attribute serialNumber rather than a Characteristic. This would allow the simpler query syntax of TMF630 Part 1:

    GET /resourceInventoryManagement/v4/resource?serialNumber=890000000000000001;890000000000000002

Expanding that for 500 values results in a URL of only 9954.

Note that there is an IETF draft for an HTTP QUERY method. If I were to invent something here I would, as Wayne Gretzky would say, "skate to where the puck is going to be". ;)

[Note: I do not speak for the TM Forum, this is merely one member's advice]

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: Jun 02, 2025 14:09
From: brian molina
Subject: standards for an api request list array and response array TMF639 resource invetory

Thank you very much advance. It really is a good help.

Today they told me that they want to send 500 simcards, meaning iccid, plus one more value of their origin.

I think about taking the option of the task resource using the POST method. and use this path /resource/querySimcardDetails , i have the request and response in array list.

POST

request

[
  {
    "type": "SimCard",
    "serialNumber": "890000000000000001",
    "resourceCharacteristic": [
      {
        "name": "channel",
        "value": "AG",
      }
    ]
  },
  {
    "type": "SimCard",
    "serialNumber": "890000000000000002",
    "resourceCharacteristic": [
      {
        "name": "channel",
        "value": "OC",
      }
    ]
  }
]

response

[
  {
    "id": "RES-890000000000000002",
    "type": "SimCard",
    "serialNumber": "890000000000000002",
    "resourceCharacteristic": [
      {
        "name": "imsi",
        "value": "700000000000001"
      },
      {
        "name": "ki",
        "value": "abc123xyz"
      },
      {
        "name": "itemCode",
        "value": "PS11111"
      }
    ],
     "place": {
          "id": "PL-XI04DP00",
          "name": "XI04DP00"
        }
  },
  {
    "id": "RES-890000000000000001",
    "type": "SimCard",
    "serialNumber": "890000000000000001",
    "resourceCharacteristic": [
      {
        "name": "imsi",
        "value": "700000000000002"
      },
      {
        "name": "ki",
        "value": "def456uvw"
      },
      {
        "name": "itemCode",
        "value": "PS11111"
      }
    ],
     "place": {
          "id": "PL-XI04DP00",
          "name": "XI04DP00"
        }
  }
]

I do this since I send 500 items per parameter get no, if it is the most advisable in your example, an array of 10 is super valid and seems excellent to me, but for larger fields, that is, more than 10, it is preferable to use task or what do you think about it?

The api will only query it with 500 json objects.

------------------------------
brian molina
TO BE VERIFIED

Original Message:
Sent: Jun 02, 2025 13:53
From: Vance Shipley
Subject: standards for an api request list array and response array TMF639 resource invetory

Brian,

If ICCID is a Characteristic you may use JSON Path to query the Resource Inventory for a match on Characteristic name and value:

    GET /resourceInventoryManagement/v4/resource?filter=resourceCharacteristic[?@.name=='ICCID' && @.value='8900000000000000001'] 

A GET of the Collection provides a response body which is an array of JSON objects of @type Resource, so it's quite normal for a query response to include multiple items. You may tailor your query to match a list of SIMs:

    GET /resourceInventoryManagement/v4/resource?filter=resourceCharacteristic[?@.name=='ICCID' && (@.value='8900000000000000001' || @.value='8900000000000000002' || @.value='8900000000000000003' || @.value='8900000000000000004' || @.value='8900000000000000005' || @.value='8900000000000000006' || @.value='8900000000000000007' || @.value='8900000000000000008' || @.value='8900000000000000009' || @.value='8900000000000000010')] 

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: Jun 02, 2025 03:30
From: brian molina
Subject: standards for an api request list array and response array TMF639 resource invetory

Okay, thanks for responding, friend. Yes, indeed, my API needs to receive a list of SIM cards with their serial numbers, and then we must return the same list but with more details. Our API is powered by three backends to provide the details. Now, the company wants us to follow TMForum standards, which seems perfect to me. But we're running into this problem. Is it convenient to create tasks with the POST method, or what can we do to retrieve an array of, say, 100 items? Using GET doesn't seem very feasible. That's why I read about the task and thought about giving my API its own path. What do you recommend I do? Sorry, I'm new to TMForum.

That's why I posted two examples. I don't know if it's valid to use /resource as the base path. And then, as I mentioned, use mine /resource/querySimcardDetails. Here, I'll leave it inside /resource because a SIM card is an inventory. Now, is it possible to use /querySimcardDetails directly as the path? Just as if it were another operation within resource-management-inventory? This is what I mean by removing /resource and adding the path directly.

------------------------------
brian molina
TO BE VERIFIED

Original Message:
Sent: Jun 02, 2025 02:13
From: Vance Shipley
Subject: standards for an api request list array and response array TMF639 resource invetory

It looks like you want to implement queries with TMF639. What you want to do is support a GET operation on the /resource collection. Simple queries may use attribute filtering with query parameters, as described in TMF630 Part 1; Chapter 4: Query Resources Patterns. Advanced queries may use JSON Path in the filter query parameter as described in TMF630 Part 6.

You seem to have an idea to invent your own query operations with a Task resource. This is something to be strictly avoided, however to answer your question, your first example would be a better choice than the second.

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: May 29, 2025 15:17
From: brian molina
Subject: standards for an api request list array and response array TMF639 resource invetory

Hello guys, I'm getting very familiar with the topic of tmforums, I have a question that always happens to us. here you go.

What happens if I have an API, for example, that I need to net on a domain, for example, the tmf639 resource inventory.

My design api receives an array list and responds with an array list with more details.

Although my API is included in the TMF639 as an inventory, it does not adapt to the raw material they handle here.

Now the assembly of my request responds, I put it together following the guidelines they define.

but I need support on which path to use
Firstly it had /resource type post but this is used in the domain to create a resource.

So I have read several forums and it says to use verbs and that this would be a task.

My question is I have 2 examples

Post /resource/querySimcard
POST /resource/simcard/query

Although I still leave my api in the resource domain but now after /resource comes the issue, I don't know if it combines part of /resource/verb with a noun

or separate the noun and the verb like example 2.

The examples I saw still don't define it well, they give me a hand

#General

------------------------------
brian molina
TO BE VERIFIED
------------------------------

Sounds like Channel is something you use to select a TMF639 producer ("backend") so out of scope for us. It does tell us that the actual number of items in an operation with a producer will be only a fraction of the 500 SIMs.

TMF639 and all TM Forum Open APIs, and REST APIs generally, manage Collections using HTTP operation POST for creation, GET for retrieval, PATCH for update and DELETE for deletion (CRUD). If your company intends to claim conformance with TM Forum Open APIs you will implement the functionality of those Open APIs. If you feel a need to also create proprietary extensions, to accommodate specific use cases, you should follow the guidelines in TMF630. The section on Task Resources provides guidance on controller type resources which perform a task which cannot be represented with the CRUD operators.  A POST is used to a URL representing a collection of Tasks which may be long running (asynchronous) or provide an immediate response (synchronous). For a synchronous Task the body is whatever you need it to be, however in your case I would suggest that it be exactly what it would be if you have used a conformant GET query operation as I have previously described and provided an example, including ResourceSpecification reference.

Okay, thanks, Vance.

If I received a list of 500 SIM cards, each with an assigned channel, is this mandatory to determine which SIM cards go to backend 1 or backend 2 depending on the channel. Then I go to backend 3 to obtain more data via the SIM card.

So, sorry to insist. This is very dedicated to SIM cards, hence my purpose of using a task resource. As I mentioned, and as I mentioned, the company won't allow me to send a lot of data via GET.

So, what could I do by joining the resourceTask, as I mentioned?
POST /resource/querySimCardDetail
with my request?

Now, in the response of this API, if I have to specify the resourceSpecification, how would the output look? Give me an example.

Q1) Multiple query parameters use AND logic. If you are querying on ICCID you are very specifically selecting an item, so adding another match seems irrelevant. You don't reuse ICCIDs across channels do you?  Now maybe communicating the channel makes the query more efficient, so you do you.

Q2) In a POST to a collection (i.e. /resource) to create an item you must NOT include id and href, however they are mandatory in a response (the index value id is generated by the API producer). The TMF630 recommendation is to NOT use "business identities" as the value of id, however it is often quite tempting to ignore that for practical implementation considerations. The value of id is opaque so how you generate it is your business as the API producer.

A ResourceSpecification is how we define the names and potential value types and constraints for resourceCharacteristics in a Resource instance. You really must provide that definition to document how to use your your API. If you aren't producing TMF634 Resource Catalog API as part of your solution you should at least provide a JSON object (@type ResourceSpecification) which can be inserted in someone else's Catalog.

Thanks Vance for responding.

I have two questions:

1. The company wants to implement APIs in tmforums. Remember how I mentioned that the get
GET /resourceInventoryManagement/v4/resource?serialNumber= 890000000000000001;890000000000000002
will not only pass serialNumber, but there are also other fields, for example, channel. With this additional field to the get, knowing that the get query will exceed 8000. So, how would I pass these fields? I understand there are no limits for this.
I really like your example according to 630 part 1:

Alternatively, the following expression [{attributeName}={attributeValue},\{attributeValue
}*] is also supported. ORING can also be explicit using ";" Many times
[{attributename}={attributevalue};{attributevalue}*]

Doing this example, the following would be a get:
GET /resourceInventoryManagement/v4/resource?serialNumber=890000000000000001;89000000000000002&channel=oc;ag

The company is more oriented toward this type of array of more than 100 items being passed per post.
However, it's a bit difficult to adapt to both company policies and tmforums, hahahahaha. Sorry.

With an urgency point, I could implement the resources task with the post method and pass my data via request ?. For example:

POST /resource/querySimCardDetail
Request:
[
{
"type": "SIM Card",
"serial number": "8934071234567890123",
"resource characteristic": [
{
"name": "channel",
"value": "AG",
}
]
},
{
"type": "SIM Card",
"serial number": "8934071234567890456",
"resource characteristic": [
{
"name": "channel",
"value": "OC",
}
]
}]

my second question:

this response that you put

{ 
"id": "93ff2da1", 
"href": "/resourceInventoryManagement/v4/resource/93ff2da1", 
"@type": "SimCard", 
"@baseType": "LogicalResource", 
"@schemaLocation": "/schema/SimCard.schema.json", 
"resourceSpecification": { 
"id": "c75578fc", 
"href": "/resourceCatalog/v4/resourceSpecification/c75578fc", 
"name": "SimCard" 
}, 
"resourceCharacteristic": []
}

I see the href field as mandatory with this value

/resourceInventoryManagement/v4/resource/93ff2da1

well here I refer for example to the id of the simcard itself, but if not I still have that get href implemented. What would I do in that case?

As I mentioned, my API will just use this TMF639 for the first time, hahaha.
And we only need it (for now)
to send a list of SIM cards, receive them, go through three backends, obtain additional information, and return the same list of SIM cards but with more details, such as KI, PUK, etc.

So, if I don't have that href implemented, do I have to implement it? Or what do I do in these cases?

In this case, I'm using polymorphism to use the serialNumber field, which is the ICCID.
So, do I also have to send these fields, baseType and schemaLocation, as required?

Finally, you mention: you use resourceCharacteristic, so I should use resourceSpecification.

I didn't know this. Is it necessary to tell the client the specification of that characteristic?

And here I have another question.

"resourceSpecification": {
"id": "c75578fc",
"href": "/resourceCatalog/v4/resourceSpecification/c75578fc",
"name": "SimCard"
}

If I don't have the ResourceCatalog API implemented yet, then I need to send this object.

What do you recommend?

I know there are a lot of questions. Sorry, I've just joined tmforums and I'm getting some context.

If you are going to claim support of TMF639 you need to first implement the standard Resource Inventory functionality. So you MUST implement this:

    GET /resourceInventoryManagement/v4/resource

The response MUST be a JSON array of objects, each having the mandatory attributes of a Resource which include id and href. If you intend to extend Resource, through polymorphism, you MUST also include @baseType, @type and @schemaLocation. If you will use the Characteristic pattern you should also include resourceSpecification.

{
    "id": "93ff2da1",
    "href": "/resourceInventoryManagement/v4/resource/93ff2da1",
    "@type": "SimCard",
    "@baseType": "LogicalResource",
    "@schemaLocation": "/schema/SimCard.schema.json",
    "resourceSpecification": {
        "id": "c75578fc",
        "href": "/resourceCatalog/v4/resourceSpecification/c75578fc",
        "name": "SimCard"
    },
    "resourceCharacteristic": []
}

Now having done this you have tethered your API to the TM Forum Open API program. Proprietary extensions MUST fit within the Open API data model by avoiding name clashes and including mandatory attributes, and should follow the patterns and practices of TMF630. If you implement a Task Resource for a specialized query the response body should be compatible with that of a GET operation.

Brian asks:
>  I do this since I send 500 items per parameter get no, if it is the most advisable in your example, an array of 10 is super valid and seems excellent to me, but for larger fields, that is, more than 10, it is preferable to use task or what do you think about it?

I would first, and foremost, implement the standard Open API.  A proprietary extension should be done out of desperation, but you would do that ALSO.

I took my JSON Path (TMF630 Part 6) example and extended it for 500 values with the resulting URL, after percent encoding, having 21633 characters. While this may seem unwieldy there is no size limit imposed on a URL by the RFCs and RFC9110 recommends that a minimum of 8000 octets be supported.

Your example however uses an extension attribute serialNumber rather than a Characteristic. This would allow the simpler query syntax of TMF630 Part 1:

    GET /resourceInventoryManagement/v4/resource?serialNumber=890000000000000001;890000000000000002

Expanding that for 500 values results in a URL of only 9954.

Note that there is an IETF draft for an HTTP QUERY method. If I were to invent something here I would, as Wayne Gretzky would say, "skate to where the puck is going to be". ;)

[Note: I do not speak for the TM Forum, this is merely one member's advice]

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: Jun 02, 2025 14:09
From: brian molina
Subject: standards for an api request list array and response array TMF639 resource invetory

Thank you very much advance. It really is a good help.

Today they told me that they want to send 500 simcards, meaning iccid, plus one more value of their origin.

I think about taking the option of the task resource using the POST method. and use this path /resource/querySimcardDetails , i have the request and response in array list.

POST

request

[
  {
    "type": "SimCard",
    "serialNumber": "890000000000000001",
    "resourceCharacteristic": [
      {
        "name": "channel",
        "value": "AG",
      }
    ]
  },
  {
    "type": "SimCard",
    "serialNumber": "890000000000000002",
    "resourceCharacteristic": [
      {
        "name": "channel",
        "value": "OC",
      }
    ]
  }
]

response

[
  {
    "id": "RES-890000000000000002",
    "type": "SimCard",
    "serialNumber": "890000000000000002",
    "resourceCharacteristic": [
      {
        "name": "imsi",
        "value": "700000000000001"
      },
      {
        "name": "ki",
        "value": "abc123xyz"
      },
      {
        "name": "itemCode",
        "value": "PS11111"
      }
    ],
     "place": {
          "id": "PL-XI04DP00",
          "name": "XI04DP00"
        }
  },
  {
    "id": "RES-890000000000000001",
    "type": "SimCard",
    "serialNumber": "890000000000000001",
    "resourceCharacteristic": [
      {
        "name": "imsi",
        "value": "700000000000002"
      },
      {
        "name": "ki",
        "value": "def456uvw"
      },
      {
        "name": "itemCode",
        "value": "PS11111"
      }
    ],
     "place": {
          "id": "PL-XI04DP00",
          "name": "XI04DP00"
        }
  }
]

I do this since I send 500 items per parameter get no, if it is the most advisable in your example, an array of 10 is super valid and seems excellent to me, but for larger fields, that is, more than 10, it is preferable to use task or what do you think about it?

The api will only query it with 500 json objects.

------------------------------
brian molina
TO BE VERIFIED

Original Message:
Sent: Jun 02, 2025 13:53
From: Vance Shipley
Subject: standards for an api request list array and response array TMF639 resource invetory

Brian,

If ICCID is a Characteristic you may use JSON Path to query the Resource Inventory for a match on Characteristic name and value:

    GET /resourceInventoryManagement/v4/resource?filter=resourceCharacteristic[?@.name=='ICCID' && @.value='8900000000000000001'] 

A GET of the Collection provides a response body which is an array of JSON objects of @type Resource, so it's quite normal for a query response to include multiple items. You may tailor your query to match a list of SIMs:

    GET /resourceInventoryManagement/v4/resource?filter=resourceCharacteristic[?@.name=='ICCID' && (@.value='8900000000000000001' || @.value='8900000000000000002' || @.value='8900000000000000003' || @.value='8900000000000000004' || @.value='8900000000000000005' || @.value='8900000000000000006' || @.value='8900000000000000007' || @.value='8900000000000000008' || @.value='8900000000000000009' || @.value='8900000000000000010')] 

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: Jun 02, 2025 03:30
From: brian molina
Subject: standards for an api request list array and response array TMF639 resource invetory

Okay, thanks for responding, friend. Yes, indeed, my API needs to receive a list of SIM cards with their serial numbers, and then we must return the same list but with more details. Our API is powered by three backends to provide the details. Now, the company wants us to follow TMForum standards, which seems perfect to me. But we're running into this problem. Is it convenient to create tasks with the POST method, or what can we do to retrieve an array of, say, 100 items? Using GET doesn't seem very feasible. That's why I read about the task and thought about giving my API its own path. What do you recommend I do? Sorry, I'm new to TMForum.

That's why I posted two examples. I don't know if it's valid to use /resource as the base path. And then, as I mentioned, use mine /resource/querySimcardDetails. Here, I'll leave it inside /resource because a SIM card is an inventory. Now, is it possible to use /querySimcardDetails directly as the path? Just as if it were another operation within resource-management-inventory? This is what I mean by removing /resource and adding the path directly.

------------------------------
brian molina
TO BE VERIFIED

Original Message:
Sent: Jun 02, 2025 02:13
From: Vance Shipley
Subject: standards for an api request list array and response array TMF639 resource invetory

It looks like you want to implement queries with TMF639. What you want to do is support a GET operation on the /resource collection. Simple queries may use attribute filtering with query parameters, as described in TMF630 Part 1; Chapter 4: Query Resources Patterns. Advanced queries may use JSON Path in the filter query parameter as described in TMF630 Part 6.

You seem to have an idea to invent your own query operations with a Task resource. This is something to be strictly avoided, however to answer your question, your first example would be a better choice than the second.

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: May 29, 2025 15:17
From: brian molina
Subject: standards for an api request list array and response array TMF639 resource invetory

Hello guys, I'm getting very familiar with the topic of tmforums, I have a question that always happens to us. here you go.

What happens if I have an API, for example, that I need to net on a domain, for example, the tmf639 resource inventory.

My design api receives an array list and responds with an array list with more details.

Although my API is included in the TMF639 as an inventory, it does not adapt to the raw material they handle here.

Now the assembly of my request responds, I put it together following the guidelines they define.

but I need support on which path to use
Firstly it had /resource type post but this is used in the domain to create a resource.

So I have read several forums and it says to use verbs and that this would be a task.

My question is I have 2 examples

Post /resource/querySimcard
POST /resource/simcard/query

Although I still leave my api in the resource domain but now after /resource comes the issue, I don't know if it combines part of /resource/verb with a noun

or separate the noun and the verb like example 2.

The examples I saw still don't define it well, they give me a hand

#General

------------------------------
brian molina
TO BE VERIFIED
------------------------------