Placement of a link to POST resource

1

I am not sure what is the best placement of a link to POST a resource. I’ll explain with an example.

I have a shift (name) parent resource (shift in the sense work period) with many shift positions (shift relationship, position relationship, required) which is related to a position (position in the sense job type, e.g. Driver).

I POST a shift resource. I want the response to include a link to the URI to consequently POST a shift position resource. I have the following three possibilities to place the create_shift_positions link:

First

{
  "data": {
    "id": "100",
    "type": "shift",
    "attributes": {
      "name": "Shift 5"
    },
    "relationships": {
      "shift_positions": {
        "data": [],
        "links": {
          "create_shift_positions": "example.org/shifts/100/shift_positions"**
        }
      }
    },
    "links": {
      "self": "example.org/shifts/100"
    }
  }
}

Second

{
  "data": {
    "id": "100",
    "type": "shift",
    "attributes": {
      "name": "Shift 5"
    },
    "relationships": {
      "shift_positions": {
        "data": []
      }
    },
    "links": {
      "self": "example.org/shifts/100",
      "create_shift_positions": "example.org/shifts/100/shift_positions"
    }
  }
}

Third

{
  "data": {
    "id": "100",
    "type": "shift",
    "attributes": {
      "name": "Shift 5"
    },
    "relationships": {
      "shift_positions": {
        "data": []
      }
    },
    "links": {
      "self": "example.org/shifts/100",
    }
  },
  "links": {
    "create_shift_positions": "example.org/shifts/100/shift_positions"
  }
}

What would be the best placement of such a link? Does the specification favor a particular approach? What would be the benefits of using one over the others?

2

Welcome!

From my perspective the first is the closest to the “right” one.

{
  "data": {
    "id": "100",
    "type": "shift",
    "attributes": {
      "name": "Shift 5"
    },
    "relationships": {
      "shift_positions": "example.org/shifts/100/shift_positions"
    },
    "links": {
      "self": "example.org/shifts/100"
    }
  }
}

With the most traditional use, the create link is implicit in the relationship URL as shown above using {json:api}.

However, if you were using affordances with the link rel hypermedia fashion as you show, the second option would be best as it is an affordance of the shift resource.

The third option in this example is to use a compound document and submit it as a single request. You would need to provide user defined id’s (UUID) for the items in the request, but this would could be replaced with self links on the newly created resources to provide their real URLs.