POSTing a nested object - returning the created nested object inside the parent

Question

Suppose that we have a Post resource (this is just a dummy example):

GET /api/posts/1

{
  "id": 1,
  "header": null,
  "content": null
}

And now we'd like to create a Header inside the Post#1.

POST /api/posts/1/header

{
  "color": "blue",
  "title": "Some title"
}

Now, is it okay for the POST request above to return the following response?

{
  "id": 1,
  "header": {
    "id": 1,
    "color": "blue",
    "title": "Some title"
  },
  "content": null
}

So, basically, a Header was created inside the Post and returned as part of the Post.

Also, if we need to GET the header for Post#1:

GET api/posts/1/header

 {
   "id": 1,
   "color": "blue",
   "title": "Some title"
}

So here only the Header is returned.

Answer 1

is it okay for the POST request above to return the following response?

Yes, that is OK.

That said, you've now got two different copies of the header; one in the representation of /api/posts/1 and one in the representation of the header resource itself in /api/posts/1/header, so you have left yourself open to the risk that different representations of the header get cached, and that the client will see conflicting representations of the two resources.

So it might be better to link to the new resource, rather than embedding its representation directly

{
  "id": 1,
  "header": "/api/posts/1/header"
  "content": null
}

("Might be" because this isn't free either; an approach like this is easier for caching, but requires at least one more round trip. Welcome to the world of tradeoffs.)

Cache is one of the important constraints in the REST architectural style; when you are designing your resource model, you should consider the implications of HTTP's standardized caching semantics.