openapi link vs hypermedia link to represent relationships in APIs

[esoni88]

Hi All,
Suppose i have a resourse Dog and a Resource Owner. i can design Dog in openapi in the following way:

Dog:
      type: object
      required:
        - id
        - name
        - owner
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string    
        ownerId:
          type: string  

in this way the client can use ownerId to get the owner data calling the api /owners/x

    Dog:
      type: object
      required:
        - id
        - name
        - owner
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string    
        owner:
          ref: $ref: "#/components/schemas/Owner"            

in this way when the client get a Dog get also all the info of the owner. The disvantages is the verbosity of response.. for each Dog the client obtain also all the info of the owner.

3. following the design best practices i can represent owner field as hypermedialink for ie /owners/1

    Dog:
      type: object
      required:
        - id
        - name
        - owner
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string    
        owner:
          type: string
          format: uri

What is the best way to design this typical situation in openapi ? in general i think the third solution is better as reported in rest best practices.
But reading the new openapi feature link
Links are one of the new features of OpenAPI 3.0. Using links, you can describe how various values returned by one operation can be used as input for other operations. This way, links provide a known relationship and traversal mechanism between the operations. The concept of links is somewhat similar to hypermedia, but OpenAPI links do not require the link information present in the actual responses.
i have some doubts... reading above i understood that the better solution in openapi is to use the first solution extended using Link

    Dog:
      type: object
      required:
        - id
        - name
        - owner
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string    
        ownerId:
          type: string   
          links:
            GetOwnerByIid:   # <---- arbitrary name for the link
              operationId: getOwner
              parameters:
                ownerId: '$response.body#/ownerId'
              description: >
                The `ownerId` value returned in the response can be used as
                the `ownerId` parameter in `GET /owners/{ownerId}`.

My idea is correct ? why openapi not suggest to use hypermedia link for relationship?

[MikeRalphson]

Note that links is a property of the Responses Object, not part of the Schema Object as you have it in your example. This may help you explore / visualise the links feature better.

why openapi not suggest to use hypermedia link for relationship?

The OAS does not suggest using design-time links information over hypermedia links, but in the latter case there is little OAS can do to annotate a hypermedia response which already has links in it.

[esoni88]

Note that links is a property of the Responses Object, not part of the Schema Object as you have it in your example. This may help you explore / visualise the links feature better.

thanks for the correction.

The OAS does not suggest using design-time links information over hypermedia links, but in the latter case there is little OAS can do to annotate a hypermedia response which already has links in it.

i dont understand .. there is a way with OAS in order to associate link to string field that represent hypermedia link ? if yes could you please do an example ?
If i understood OAS links are client computed, in order to link different operations.. typically a field of the response is used as parameter of other operations. Hypermedia link is typically URI of other resourse.
Suppose i have a field
owner:
type: string
format: uri
example: /owners/1

It would be useful if OAS allow to use this field in link definition in order to describe that the content of owner field is the link to operationId getOwner.
Is it possible actually ?
if not @MikeRalphson , what do you suggest for my example Dog -> Owner ? how would you design in OAS the entity Dog and the relationship with Owner ?
Thanks a lot,
Dario

[safareli]

being able to use OAS link with basic Hypermedia links would be great. Tho some apis might include relations array in resources. this are spec for some predefined relation types but one can define custom relations as well.

With that approach response of GET http:https://myApi.com/cats/ would look like this:

{
  "items": [
    {
      "id": 1,
      "name": "mewfoxy",
      "links": [
        { "rel": "self", "href": "http:https://myApi.com/cat/1" },
        {
          "rel": "http:https://myApi.com/relationshps#owner",
          "href": "http:https://myApi.com/user/66"
        }
      ]
    },
    {
      "id": 2,
      "name": "mewFoo",
      "links": [
        { "rel": "self", "href": "http:https://myApi.com/cat/2" },
        {
          "rel": "http:https://myApi.com/relationshps#owner",
          "href": "http:https://myApi.com/user/11"
        }
      ]
    }
  ],
  "links": [
    { "rel": "self", "href": "http:https://myApi.com/cats" },
    { "rel": "next", "href": "http:https://myApi.com/cats?page=2" },
    { "rel": "last", "href": "http:https://myApi.com/cats?page=20" }
  ]
}

[handrews]

This scale of change is best discussed in Moonwalk (and can be backported if relevant and we decide to keep the 3.x line going). Closing in favor of:

• Improvements for links in v4 sig-moonwalk#58
• Resource oriented sig-moonwalk#30