Creating a new event

Story

As an application user I want to be able to create new events manually So I can have event's I'm aware of added to my calendar.

As an API consumer I want to be able to create new resources of a given type So I can produce content.

Usage

const event = {
    "@context": "/api/context.jsonld",
    "@type": "schema:Event",
    "eventName": "My brand new event",
    "eventDescription": "Hope it will work",
    "startDate": "2017-04-19",
    "endDate": "2017-04-19"
};
const operation = await hydraClient
    .getApiDocumentation("http://example.com")
    .supportedClasses.ofType("http://schema.org/Event")
    .operations.ofType("http://schema.org/CreateAction")
    .first();
await hydraClient.invoke(operation, event);

Details

The application has to be aware of how it can create a new resource. It could get that information either from the API documentation or entry point or last response's hypermedia controls. It also have to understand the type of resource in scope (unless it is provided from outside of the application, i.e. pass-through import from external data source).

Anyway, assuming all the requirements are met, a request would look like this:

POST /api/events

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

HTTP 201 Created
Location: /api/events/2

Brand new event should be now added to the calendar.

Considerations

Protocol agnostic specification

While the most popular protocol in use is currently HTTP, ReST API can be implemented on top of other protocols. The example above has a weaknesses of being strictly bound to HTTP by referring to HTTP POST method. This has also another weakness - server may also allow to create resources using HTTP PUT, or it may go event further - it can forbid the POST method in favor of PUT. Specification could be protocol agnostic and give some hints on the logical functions of the operations. Possible solution could be to use i.e. schema.org actions, but without specification being clear about that, using schema.org actions is just one of possible solutions. There is nothing against using other vocabularies causing the Hydra Core Vocabulary to be prone to dialects and variations. This leads to another weakness - first though can go in the CRUD direction, but these are not the only approaches available in the wilderness (not to mention that there are voices that put using CRUD in ReST API to question).

Creating user interfaces

It is common that rich UI applications allows their users to create/edit resources via some forms full of inputs, lists etc. The question is - how these should be created.

The easiest approach is to hard-code these in the application. Well, if the application knows how to handle resources of type Event, it would have some of the logic and views already prepared. The issue here is that it somehow puts the whole idea of meta-data to question. If we have tools to fully drive the client, why not use them?

Another, slightly better solution would be to embed some of that logic within the hypermedia controls. This is what happens when an HTML page has JavaScripts, CSS's and HTML forms embedded - client receives extra stuff to be used to show the form so it sends the resource back to the server. In our case though, it somehow puts on to our API a burden of being aware of the client UI capabilities, which seems to be a dead end.

Ultimate solution would be to give the client all the details possible about the resource itself, it's structure, data types etc., so the client can use these on it's own.

We need to mention also a hybrid-like solution for non-UI applications. Server side could provide a template of a resource to be filled with data. Still, the client would need some more details so the template receives correct values.

5 Creating new event