More clarification on resource linking

[JDMKSZ]

1. Rule [hyp-links] says:

   When referencing another resource within the same API, a link SHOULD be added using the href attribute.

   Does this apply for referencing refData resources as well? So next to a "code" or "type" property, a "href" should be present? And if so, do we need to add an extra "level"? So is it:

   CivilStatusWithLink:
     allOf:
       - $ref: "belgif/common/v1/common-v1.yaml#/components/schemas/HttpLink"
       - type: object
         properties:
           type:
             $ref: "belgif/person/v2/person-v2.yaml#/components/schemas/CivilStatusTypeCode"
           partner:
             $ref: "#/components/schemas/RelatedPerson"
           validityPeriod:
             $ref: "#/components/schemas/ValidityPeriodIncompleteDateOptionalEnd"
   

   or

   CivilStatusWithLinkAndLevel:
     type: object
     properties:
       type:
         allOf:
           - $ref: "belgif/common/v1/common-v1.yaml#/components/schemas/HttpLink"
           - type: object
             properties:
               id:
                 $ref: "belgif/person/v2/person-v2.yaml#/components/schemas/CivilStatusTypeCode"
       partner:
         $ref: "#/components/schemas/RelatedPerson"
       validityPeriod:
         $ref: "#/components/schemas/ValidityPeriodIncompleteDateOptionalEnd"
   

   or can we do without the HttpLink for refData, like this:

   CivilStatusWithoutLink:
     type: object
     properties:
       type:
         $ref: "belgif/person/v2/person-v2.yaml#/components/schemas/CivilStatusTypeCode"
       partner:
         $ref: "#/components/schemas/RelatedPerson"
       validityPeriod:
         $ref: "#/components/schemas/ValidityPeriodIncompleteDateOptionalEnd"
   

2. Related question. Chapter 11.1 at the end says: > The use of Web Linking and Hypertext Application Language (HAL) is not recommended.

   What is the recommendation about using OpenAPI 3.0 links ?

[pvdbosch]

1. That may be up for debate. Having a lot of hrefs could clutter responses and increase implementation effort; we're not too strict on it in practice. Then again, an additional level can be interesting if you want to include an inline code description.

2. Not sure if adding OpenAPI 3 links is worthwhile:

• haven't tested yet if it does something for generated code
• it's only documentation, doesn't change what's sent over the wire so wouldn't hurt to add it
• it shows up in SwaggerUI but still quite difficult to interpret, and the description of the "id" property would be clear enough IMO in this case:

[pvdbosch]

"civilStateType": 1

vs.

civilStateType: { "code": 1, "href": "https://myapiUrl.be/thisSameApi/v1/refData/civilStateTypes/1" }

vs inline description "civilStateType": { "code": 1, "description": { "nl": "gehuwd", "fr": "...", "de": "..." } }

response of refData: { "code": 1, "description": { "nl": "gehuwd", "fr": "...", "de": "..." } "validityPeriod": {....} }

current guideline is quite strict: e.g. in collection resources "In these objects, a href property MUST be present with a link to the resource."

fps fin:

• hrefs (with absolute URIs) often not used because difficulty changing them when hostname changes
• often query param flag to include code descriptions inline, but also refData included in same API

eHealth:

• refData to obtain internationalized descriptions, cached in client
• geen href

Smals:

• BFFs APIs where descriptions are often inlined
• often no href together with code values
• API Gateway does URL rewriting in responses if backend hostname is detected in JSON

CBSS:

• currently apply REST guide strictly, but open for other options for refData

REST WG decided to review the rules around href in general, also provide clarifications on embedding vs inlining other resources. Will be prepared for a next meeting