Updating an existing event

Story

As an application user I want to be able to update an existing events manually So I can have store some additional details bound to those events.

As an API consumer I want to be able to update existing resources of a given type So I can amend content.

Usage

const event = await hydraClient.getResource("http://example.com/api/events/1");
event.eventName = "Some new event name.";
await hydraClient.invoke(
    event.hypermedia.operations.ofType("http://schema.org/ReplaceAction").first(),
    event);

Details

Application needs to be able to modify existing resources. This use case relies on the fact, that the resource is first obtained from the server, amended and sent back, but this is not always true. Additional, the operation used for the update is taken from the hypermedia controls embedded in the resource and the target method is discovered with an anti-patter binding it to HTTP protocol. Regardless all of these, the communication would look like the example below:

GET /api/events/1

HTTP 200 OK

{
    "@context": "/api/context.jsonld",
    "@id": "/api/events/1",
    "@type": ["schema:Event"],
    "eventName": "My brand new event",
    "eventDescription": "Hope it will work",
    "startDate": "2017-04-19",
    "endDate": "2017-04-19",
    "operation": [
        {
            "@type": ["Operation", "schema:ReplaceAction"],
            "title": "Update an existing event",
            "method": "PUT",
            "expects": "schema:Event"
        }
    ]
}

PUT /api/events/1

{
    "@context": "/api/context.jsonld",
    "@id": "/api/events/1",
    "@type": "schema:Event",
    "eventName": "Some new event name.",
    "eventDescription": "Hope it will work",
    "startDate": "2017-04-19",
    "endDate": "2017-04-19"
}

HTTP 204 No Content

The event should be now updated.

Considerations

What does the term "update" means?

As mentioned in the previous use case, the application is not aware of the kind of data that will be provided by the server, thus a simple question arises:

What gets updated?

The simplest answer would be that whole resource is replaced with new incoming data. But it is easy to imagine a situation, where a client may explicitly state what kind of data to include when obtaining a resource, thus server won't know which data to update and which to leave untouched. These considerations could multiplied, thus some explicit directions may be needed.