Misleading endpoint name `/iolink/v2/gateway/configuration`

[thbauer-pepperl-fuchs]

The endpoint /iolink/v2/gateway/configuration has a misleading name and problematic API design that should be
addressed.

Problems

1. Misleading Endpoint Name

Current: /iolink/v2/gateway/configuration

Issue: The endpoint name suggests it contains the full device configuration, but it only handles Ethernet IPv4
addresses and network configuration.

Proposed Solution: Rename to /iolink/v2/gateway/network to clearly indicate it's network-specific configuration.

2. Inconsistent Property Naming

Current: ipConfiguration

Issue: The name doesn't clearly convey its purpose. Additionally, other protocols like DCP can also assign IP
addresses to devices, so the naming should reflect that this is about the IP address assignment method.

Proposed Solution: Rename to ipAddressMethod or ipAssignmentMethod to better describe what the property
controls.

3. Schema Design Issues

Current Description from Schema:

The properties ipAddress, subnetMask and standardGateway are only allowed for POST, if ipConfiguration is set to
MANUAL. They are mandatory for GET.

Issue: This indicates properties that are conditionally read-only or write-only, but the schema doesn't properly use
readOnly: true or writeOnly: true to reflect this.

Proposed Solution: The schema should use proper OpenAPI specifications:

• Use conditional schemas (oneOf) to represent different POST request structures
• Properly mark fields with readOnly or writeOnly where applicable

4. API Structure for Different IP Configuration Modes

Current Issue: The API doesn't clearly differentiate between MANUAL and DHCP (or other methods like DCP) in the
request structure.

Proposed POST Request Structures:

Option A: Manual IP Configuration

{
  "ethIpv4": [
    {
      "ipAddressMethod": "MANUAL",
      "ipAddress": "192.168.1.13",
      "subnetMask": "255.255.255.0",
      "standardGateway": "192.168.1.1"
    }
  ]
}

Option B: DHCP Configuration

{
  "ethIpv4": [
    {
      "ipAddressMethod": "DHCP"
    }
  ]
}

Option C: DCP or Other Protocols

{
  "ethIpv4": [
    {
      "ipAddressMethod": "DCP"
    }
  ]
}

Recommended Changes

1. Rename endpoint from /iolink/v2/gateway/configuration to /iolink/v2/gateway/network
2. Rename property from ipConfiguration to ipAddressMethod or ipAssignmentMethod
3. Update schema to use OpenAPI oneOf or anyOf to properly model the conditional structure:
   • When ipAddressMethod is MANUAL: require ipAddress, subnetMask, and standardGateway
   • When ipAddressMethod is DHCP, DCP, or other methods: these properties should not be included in POST
     requests
4. Update documentation to clearly explain the different IP assignment methods and their respective
   required/optional fields
5. Use proper OpenAPI attributes like readOnly and writeOnly where properties differ between GET and POST
   operations

[roesekoSICKAG]

Discussion in WG meeting (2026-02-04):

1. Rename endpoint from /iolink/v2/gateway/configuration to /iolink/v2/gateway/network -> Of course the new endpoint name would be more descriptive but regarding compatibility it will not be changed.
2. Rename property from ipConfiguration to ipAddressMethod or ipAssignmentMethod -> Good point. Will do ipAddressMethod👍
3. Update schema to use OpenAPI oneOf or anyOf to properly model the conditional structure. -> There might be problems with the OpenAPI Generator. See also Bugfix specification for pathparameter parameterIdent #201.
4. Update documentation to clearly explain the different IP assignment methods and their respective required/optional fields -> Yes, will do.
5. Use proper OpenAPI attributes like readOnly and writeOnly where properties differ between GET and POST operations -> Yes, will do.

[thbauer-pepperl-fuchs]

Regarding Point 1

I don't understand the reasoning behind rejecting the endpoint rename for "compatibility" reasons. We are defining
version 2.0.0 of the OpenAPI specification for IO-Link Master devices. This is a major version release, which by
semantic versioning explicitly allows breaking changes.

The endpoint /iolink/v2/gateway/configuration is clearly misleading when it only handles network configuration. If we
cannot fix such obvious design flaws in a major version, then we're setting a precedent that prevents us from ever
cleaning up poorly designed APIs - simply because "we need to be backward compatible."

This creates a contradiction:

• If we truly need backward compatibility, then the base path /iolink/v2 itself is the first mistake, as it already
  suggests breaking changes from v1.
• Major versions exist precisely to allow us to fix design issues without the burden of backward compatibility.

The whole purpose of incrementing to v2.0.0 is to allow breaking changes. Otherwise, why version at all? We should
be able to improve naming, structure, and clarity in major releases. If not now, when?

I strongly recommend we use this opportunity to rename the endpoint to /iolink/v2/gateway/network for better API
design and maintainability.

[filip-42]

@thbauer-pepperl-fuchs, @roesekoSICKAG Isn’t it the case that all configurable parameters are modified via the */configuration endpoint schema? Introducing an additional /network endpoint would break this schema. The /configuration endpoint is designed to be generic and to include all modifiable parameters. If another configurable parameter needs to be added, it is straightforward to extend the request/response body accordingly.

[thbauer-pepperl-fuchs]

Thank you for pointing out the */configuration pattern — I hadn't fully noticed that schema, so I appreciate the hint.

However, looking at this more closely, it actually reinforces my concern about consistency. The API mixes two different
design approaches:

1. Some endpoints follow a */configuration pattern where GET and POST operate on the same resource (e.g.,
   /iolink/v2/mqtt/configuration uses GET to read and POST to write the configuration).

2. Other endpoints follow a more RESTful pattern where the resource itself is the noun (e.g.,
   /iolink/v2/mqtt/topics supports GET, POST, and DELETE directly on the resource collection, and
   /iolink/v2/mqtt/topics/{topicId} operates on individual items).

This inconsistency makes the API harder to reason about — some parts look like REST, others do not.

Regarding the network configuration specifically: if we follow the existing */configuration convention, it should be:

GET / POST on /iolink/v2/gateway/network/configuration

Or, if we follow the RESTful pattern used elsewhere in the spec:

GET / POST on /iolink/v2/gateway/network

Either approach would be fine with me, but it should be consistent with how other similar resources are handled in the
specification.

[roesekoSICKAG]

Discussion in WG meeting (2026-03-16):
This will not be solved in 2.0.0 and postponed to a later version.