Add IRIs for created objects in response for POST and PUT request.

[farazkhanfk7]

I'm submitting a

• [ ] bug report.
• [x] feature request.

Current Behaviour:

After discussion on slack group we realised that some more details can be added in the response that is returned after a new object is created or updated using PUT/POST request. Currently, the response is in this format:

{
    "@context": "http://www.w3.org/ns/hydra/context.jsonld",
    "@type": "Status",
    "description": "Object with ID f3744cd9-1921-49f6-9caa-c6676678b029 successfully added",
    "statusCode": 201,
    "title": "Object successfully added."
}

We can add full IRIs for the created object as well, which will make it easier to reference the link or perform operations on the newly created/updated object.

Expected Behaviour:

IRI for the object can be added in the response body.

{
    "@context": "http://www.w3.org/ns/hydra/context.jsonld",
    "@type": "Status",
    "description": "Object with ID f3744cd9-1921-49f6-9caa-c6676678b029 successfully added",
    "iri": "http://localhost:8080/serverapi/Movie/f3744cd9-1921-49f6-9caa-c6676678b029",
    "statusCode": 201,
    "title": "Object successfully added."
}

Steps to reproduce:

Make a PUT/POST request to any Class or Collection endpoint.

Snapshot:

Environment:

* python version * pip version * OS details ### Do you want to work on this issue?

Yes

[priyanshunayan]

@farazkhanfk7 Why are we using iri keyword instead of @id keyword? To me using iri seems opinionated. Also according to the JSON-LD docs:

A string is interpreted as an IRI when it is the value of an @id member

[farazkhanfk7]

@priyanshunayan Yes, I had the same thing in mind at first as we also have @id in HydraStatus class in core repo. It's just that we're not using it yet. But I changed it to iri as suggested by @Mec-iS on slack, so that we can use it for id of created or updated objects.

@id of a status is the uri of the status response (or its schema), not the id of the object created See Conversation

[Mec-iS]

As already mentioned, @id in a response status payload is the URI to the actual status response schema.

If we want to add the id of the created object we need to supply an additional property; as discussed this property (for example "uris" or "iris") should provide a list of created objects.

Please remember that "@id" is one of the special-purpose property in Hydra as it is part of the syntax (like all properties that start with @) so it has a very precise meaning in a playload.

[priyanshunayan]

As already mentioned, @id in a response status payload is the URI to the actual status response schema.

Makes sense. Thanks, @Mec-iS

Was there any specific reason that we chose to return the status in the response rather than the created object itself? While I was going through the cookbook I noticed the expected response from the API contained the newly created object itself- https://github.com/HydraCG/cookbook/blob/master/movies/create-movie.md We are anyways sending the status code in headers as well. Can we think of returning the created object instead of verbose status in the response?

[farazkhanfk7]

This is actually interesting, they're returning the object itself in the response. But should we do that instead of @type : Status ? and what should be returned in case of hydra: Collection ?

[Mec-iS]

this is something @sameshl and @chrizandr can answer as it is a hydrus design choice

[EDIT] btw returning the full created object or objects would be unjustified in terms of cost (bandwidth), the client already knows which data it submitted. Again PUT response should not have a body according to RFC 7231 section 4.3.4

[EDIT] Plus, the objective of Hydra is mainly to be a "semantic layer" on top of API data, so it makes sense that what is returned is more a "semantic annotation" of the data stored than actual data.

[priyanshunayan]

the client already knows which data it submitted

@Mec-iS The client does not at which location the data was stored.

According to this RFC: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2, when 201 status code is returned:

The response SHOULD include an entity containing a list of resource characteristics and location(s) from which the user or user agent can choose the one most appropriate.

[Mec-iS]

@priyanshunayan

Was there any specific reason that we chose to return the status in the response rather than the created object itself?

I was replying to this question above, not about the feature proposed in the issue; Please read more carefully next time.

According to this RFC: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2, when 201 status code is returned:

that is implied in what I wrote in the Slack discussion before the PR was open.