Update CAMARA_common.yaml: add Device headers, fix address

[Kevsy]

Fixes #118 #119

What type of PR is this?

Add one of the following kinds:

• correction
• enhancement/feature

What this PR does / why we need it:

• Adds HTTP Headers for Device Identifiers, for reuse in APIs with GET methods requiring protection for Device Identifiers
• Changes instances of Addr to Address in object names.

Which issue(s) this PR fixes:

Fixes #118
Fixes #119

Special notes for reviewers:

Changelog input

 release-note

Additional documentation

This section can be blank.

docs

[patrice-conil]

LGTM
But as this will impact many existing APIs (as IP addresses are often used) we need to ask other companies for their opinions.

[rartych]

Thank you @patrice-conil for pointing this out. As this small change: Addr to Address impacts subprojects like Device Identifier, Device Status and Device Location, QoD I am adding @eric-murray @bigludo7 @jlurien and @hdamker as reviewers.

Note: for IPv6 the DeviceIpv6Address name is used.

[jlurien]

Why not using same format for all schemas? If we use UpperCamelCase for schema names, it is more coherent to use them as well here, e.g. Ipv4Address

[Kevsy]

By convention HTTP headers are Kebab-Case: RFC 2616, section 5.3. So IPv4-Address uses the same naming style because it is an HTTP Header. "DeviceIpv4Address" is the schema that the parameter is based on (which follows CAMARA UpperCamelCase convention for schema names).

[PedroDiez]

Hi Kevin,

Understood and OK to use kebab-case for the parameter property value. I checked with Jose, he was refering only to use UpperCamelCase for the schema name, just for aligment. Usually code generators also works better with schemas named following Camelcase. So it would read (just removing "-", for the new schemas included):

IPv4Address:
in: header
name: IPv4-Address
required: false
schema:
$ref: "#/components/schemas/DeviceIpv4Address"

WDYT?

[jlurien]

Thank you @patrice-conil for pointing this out. As this small change: Addr to Address impacts subprojects like Device Identifier, Device Status and Device Location, QoD I am adding @eric-murray @bigludo7 @jlurien and @hdamker as reviewers.

Note: for IPv6 the DeviceIpv6Address name is used.

The change affects code generation as those names are schema names that may be mapped to classes. The API itself does not change.

[jlurien]

• Adopt UpperCamelCase for parameters schemas

[Kevsy]

• Adopt UpperCamelCase for parameters schemas

The schemas for the new parameters do have UpperCamelCase names.

But the parameter names (that reference the schemas) have Kebab-Case names, because they are specifically HTTP header parameters, which follow the convention in RFC 2616, section 5.3.

[PedroDiez]

Another comment: As it has been defining models por "headers" params, this model is not wide enough to cover with serialziation topics:

https://swagger.io/docs/specification/describing-parameters/#header-parameters
https://swagger.io/docs/specification/serialization/

Header Parameters

Header parameters always use the simple style, that is, comma-separated values. This corresponds to the {param_name} URI template. An optional explode keyword controls the object serialization. Given the request header named X-MyHeader, the header value is serialized as follows:

style | explode | URI template | Primitive value X-MyHeader = 5 | Array X-MyHeader = [3, 4, 5] | Object X-MyHeader = {"role": "admin", "firstName": "Alex"} -- | -- | -- | -- | -- | -- simple * | false * | {id} | X-MyHeader: 5 | X-MyHeader: 3,4,5 | X-MyHeader: role,admin,firstName,Alex simple | true | {id*} | X-MyHeader: 5 | X-MyHeader: 3,4,5 | X-MyHeader: role=admin,firstName=Alex

^* Default serialization method

Header Parameters Header parameters always use the simple style, that is, comma-separated values. This corresponds to the {param_name} URI template. An optional explode keyword controls the object serialization. Given the request header named X-MyHeader, the header value is serialized as follows:

style explode URI template Primitive value X-MyHeader = 5 Array X-MyHeader = [3, 4, 5] Object X-MyHeader = {"role": "admin", "firstName": "Alex"}
simple * false * {id} X-MyHeader: 5 X-MyHeader: 3,4,5 X-MyHeader: role,admin,firstName,Alex
simple true {id*} X-MyHeader: 5 X-MyHeader: 3,4,5 X-MyHeader: role=admin,firstName=Alex

• Default serialization method

[PedroDiez]

To summarize the comments:

- Comment 1: It can be used "UpperCamelCase" as model for schema convention which does not preclude to name a parameter which is a header as kebab-case notation

  IPv4-Address:
   in: header
   name: IPv4-Address
   required: false
   schema:
    $ref: "#/components/schemas/DeviceIpv4Address"

- Comment 2: With regards to the schema model to refer to a "header".

• It would be needed to align on the serialization mode. (probably explode=true)
• At least IPv6-Address "header" definition points to schema that is an object so this would need to define the serialziation mode

cc @Kevsy (we talked in 25th March Commonalities meeting about this PR)

[Kevsy]

@PedroDiez , @rartych , please can you propose any further changes as a new commit of the PR? I believe Comment 1 above is already implemented in the current commit, but I'm not sure what is the decision on Comment 2.

[rartych]

@PedroDiez @Kevsy I see headers for device identification are used in https://github.com/camaraproject/SimpleEdgeDiscovery/pull/4/files
All defined headers are simple strings, so the serialization is not needed.

The IPv4-Address header is defined as follows:

        - name: IPv4-Address
          in: header
          required: false

          schema:
            $ref: "#/components/schemas/SingleIpv4Addr"

Do you think this approach can be used here? But replacing SingleIpv4Addr with proposed SingleIpv4Address ?
This can be also the move in the direction indicated in #171 .