Should event types be plural?

[joelvogt]

A RESTful interface expects EPCIS event types, which are collections, to be plural. In the EPCIS data model, EPCIS event types are singular. Do we keep event types plural or singular in the resource path? If we keep them plural, are they singular or plural in the EPCIS query?

[mgh128]

Within the URL query parameters, the eventType parameter should expect ObjectEvent, AggregationEvent etc. expressed in the singular form, for consistency with what is defined in section 8.2.7.1 of EPCIS v1.2 in the table following line 2108 on page 71. Chapter 8 of EPCIS v1.2 is still describing at an abstract level how the capture and query operations should work, independent of any particular binding, so the URL query parameters should agree with that, also for the REST interface.

The challenge we have in EPCIS 2.0 and its REST interface is that we're trying to find the best solution for two distinct communities:

1. The existing EPCIS 1.2 community migrating to REST, who are used to ObjectEvent, AggregationEvent etc. always being singular - and who might find it confusing that REST collections use a plural form, e.g. /events/ObjectEvents
2. The REST developer community who are new to EPCIS, who are used to expecting plural forms for collections - and who might be confused if we used a singular form, e.g. /events/ObjectEvent

I think we need to ask the group to decide whether we should use the singular or plural form for collections, e.g. /events/ObjectEvent vs /events/ObjectEvents

Either way, we need very clear guidance in the REST chapter about whatever we decide for collections (singular / plural) - and why we decided it. If we opt for a singular form for the collection name, then the REST OpenAPI documentation would probably also need to include a disclaimer to say that we're doing something not quite RESTful - and here's why.

[dakbhavesh]

Hi @mgh128,

In my humble opinion, we are not violating any REST convention here. The REST endpoints comprising of {eventType} path variable expects event type value which is supposed to be either of ObjectEvent, TransformationEvent, AggregationEvent etc.

Here {eventType} should be considered just as a type of event which eventually help in forming query in the backend. It shouldn't be deemed as collection. It can be considered as other similar parameters for e.g. {queryName}, {bizLocation}, {disposition} etc.

If we keep plural forms then it will be very inconvenient for implementors to convert them into their corresponding singular form.

[mgh128]

Hi @dakbhavesh ,

I agree with you that it will probably be less confusing for our EPCIS community if ObjectEvent etc. always appear in the singular form.

At https://restfulapi.net/resource-naming/ there is some guidance on resource naming.

In most or all of their examples, the variable name in curly brackets identifies a single entity within a collection, e.g. a specific user (selected by its user ID) within a collection of users.

With {eventType} it could be argued that we are selecting one specific type (e.g. ObjectEvent) or sub-collection within the set of all defined types ( ObjectEvent, AggregationEvent, TransformationEvent, TransactionEvent, AssociationEvent ).

In a parallel universe, we might have done things differently and instead two of our REST endpoints might have been:

/events (returns the collection of EPCIS events of any type) /eventTypes/{eventType}/events (still returns a collection of /events but already pre-selected for a specific event type)

then I think it's clear that eventTypes corresponds to the 5 standard defined event types and we're selecting one.

To me, that approach seems more closely aligned with the naming convention at https://restfulapi.net/resource-naming/

Furthermore, with this formulation, it's clear from the endpoints at /events and /eventTypes/{eventType}/events that both return a set of events - and it's also very readable that the endpoint at /eventTypes/{eventType}/events has a pre-filter on event type expressed in the URI path info.

GET /eventTypes would list all support event types (e.g. ObjectEvent, AggregationEvent etc.) GET /eventTypes/ObjectEvent would list the methods, resources or collections available for ObjectEvent, including the /events collection

So I think this approach works well in a RESTful / HATEOAS way and potentially overcomes our conundrum about whether it should be ObjectEvent or ObjectEvents - because with this formulation, we're selecting one event type (therefore singular form) from within 5 defined /eventTypes - and the /event collection follows after that, rather than preceding {eventType}

@joelvogt - What do you think? I'm not intending to create extra work for you - but do you think /eventTypes/{eventType}/events is a more RESTful / HATEOAS approach that we should consider ?

[dakbhavesh]

Just wen't through https://restfulapi.net/resource-naming/ and found it nicely describing the sub-collection as part of parent collection.

e.g.

• accounts (sub-collection) of a specific bank customer
• friends (sub-collection) of a linked-in/facebook user
• assets (sub-collection) of an organisation

In our case {eventType} is not fitting well as sub-collection. Because we can't say ObjectEvent is sub-collection of any particular event. In general, we are dealing with single resource i.e. events with lots of attributes. Some good example of sensible sub-collections would be /ObjectEvent/{eventId}/origins or /ObjectEvent/{eventId}/sensors etc. Sub-collection usually returns completely different structure than it's enclosing resource in response.

/eventTypes/{eventType}/events => this kind of endpoints are sort of awkward because /eventType doesn't resemble any tangible resource. I would be bit against to include as it will make REST api bit verbose.

Also, have a question about usability of /events/{eventType}: In practice, users may rarely want to filter events by type without any additional filters as in all domains there would be millions / billions events of specific type in repository. Don't mean to remove this endpoint but never found such endpoints usable except some ad-hoc developer level testing purposes.

[mgh128]

I think I agree with your statement 'Sub-collection usually returns completely different structure than it's enclosing resource in response.' .

The final component of the URI path info should indicate what kind of collection you can expect to receive.

If we want to receive a collection of events, then /events should really be in the final position in the URI path info

I think /eventTypes is just as intangible as /bizSteps or /dispositions - like eventType, those are also concepts rather than real world objects.

We already have support for

/dispositions/{disposition}/events (which returns an events collection for a single selected disposition e.g. 'in_transit') /bizSteps/{bizStep}/events (which returns an events collection for a single selected bizStep such as 'shipping')

{eventType} is just another intangible concept and selector / filter. In the case of AggregationEvent it is often closely connected with packing / unpacking values of bizStep.

/eventTypes/{eventType}/events would just follow the same pattern. It returns an events collection for a single selected event type.

I do agree with you (@dakbhavesh ) that most EPCIS queries will want to specify some combination of an object, a place and possibly a time-window or a bizStep value in order to receive a sufficiently small and relevant set of events for their query - and that it might not be particularly useful to express the filter for event type in the URI path info when they can anyway select / constraint it in the URI query string.

[joelvogt]

@mgh128 extra work is no problem, if it helps to improve the specs, I'm all for it. The API is already RESTful. We designed after studying other APIs and best practices. And EVRYTHNG has years of experience in this domain, which also helped to the design. To me, the question, should event types be singular or plural, is about making a reasonable user experience/ RESTful tradeoff. If being RESTful was our only design choice, we wouldn't have to ask the group. In REST, collections are plural. But I also understand that the data model is based on a class diagram and classes are often singular.

As a side note, I suggested the /events/eventType template to represent the EPCIS events ontology. But if event types don't really matter and all events have the same properties, this could be a good opportunity to update the model accordingly.

[mgh128]

Hi @joelvogt

It's not quite correct that all events have the same properties or that a specific property can be used with each event type. For example, TransformationEvent has no action field. parentId and childEPCs cannot be used in an ObjectEvent. The UML class diagram would certainly be much simpler if all events had the same properties - but they don't and there are good reasons for that.

It is sometimes useful to be able to select a specific event type, but that's only one parameter / constraint among many and it's often not even the most important query parameter even though on a UML class diagram it might appear to be a primary filter / selector.

When we think about doing end-to-end tracking/tracing to navigate along a supply chain (something looking a bit like this: https://milecastle.media/dev2016/traceability-demo/ ) we typically ask for events for a specific EPC, sort them into timestamp order and then analyse the events we actually receive to determine which query to formulate next. If we received an aggregation event that stated that the original EPC has been packed into a container, then we'll probably want to then ask for event data about the container. Neither of those queries really specified the event type - but receiving an event of a particular type and bizStep value led us to update our state model and decide what query to ask next. There are other situations where we might know a transaction ID and a supplier or shipping party and maybe even an EPC class or GTIN but we don't know which specific SGTINs we will receive - but we formulate a standing query for events that batch a particular purchase order transaction ID.

We all want it to be as usable and intuitive as possible.

[joelvogt]

Group voted in favour of singular, to keep EPCIS type names consistent in queries and paths and the event type can be seen as an instance of events, in which case keeping it singular is acceptable.

[CraigRe]

Prematurely closed; now continued in issue 53: https://github.com/gs1/EPCIS/issues/53#issue-744872895