Event id in the returned data payload

[mcolynuck]

Perhaps I'm just not seeing it but I was looking at the example of the xml payload for an event that is returned to the user. I expected to see an element with the ID for the event but about all I can find with that information is the url back to the api for that event:

I'm thinking of a situation where I query the api for bulk data. Extracting it from the link is not that difficult but it doesn't seem 'obvious' that this is the way to get the ID value. If I query the api for the specific event, I'll already have the ID but when searching by other parameters such as geography, severity, etc., you need to retrieve them from the reply payload.

Should an 'ID' be added to the standard or should the link with rel="self" be parsed to obtain the event ID?

[michaelmulley]

So the idea isn't so much that the event's URL be parsed to obtain the event ID as that the event's URL is the event ID. It's a unique string that identifies the event, with the added bonus of encoding how to get the most recent version of the event.

Implementations are of course going to have some kind of internal ID field, which will likely form some component of the URL. But the Open511 API doesn't include any concept of event ID other than the URL, and you never need any other kind of ID to use the API.

That said, if this kind of design purity ends up confusing users, it's not worth it. I don't have any particular problem with doing something like:

<event>
    <link rel="self" href="http://dev.open511.ca/api/events/mtq.open511.ca/min43104/" />
    <id>mtq.open511.ca/min43104</id>

Does that seem friendlier to you? If so, I can discuss this with our other collaborators and see whether they too prefer adding a field like that.

[mcolynuck]

I would not want the id to be implemented in this way. However, it does solve the problem of my consumer application knowing exactly where to locate the url by the tag name. I think that's the main problem I have with the current implementation. The url is an attribute of a generic link so to programmatically find this information I have to loop through all the links (of which there may be many or few, I don't yet know) and look for clues (i.e. rel="self" or parse the href value), hoping I had the right one.

To put it in other terms, consider trying to retrieve an html element with javascript when the element tag does not have an id or name. You either locate another element and reference the one you really want from there, or step through all element siblings, children and parents or retrieve all elements of that tag type and just loop through them. Compare that to retrieving the element by its id attribute. If for example, this link tag had an attribute like 'name="event_id"' then it would be fairly easy to find with complete certainty among the other event data.

By comparison, I noticed that jurisdiction xml data example had an id tag. This example uses an id that happens to also be a part of the 'self' link url. Just to clarify, would the id value not always be the same as found in the url? Should that id tag be removed to maintain consistency?

mycity.gov You're right in how I use the id value internally is up to the consumers needs, whether the whole url or a portion of it. I just want to be sure I can retrieve it easily and with total certainty. On 27 June 2013 17:51, Michael Mulley notifications@github.com wrote: > So the idea isn't so much that the event's URL be parsed to obtain the > event ID so much as that the event's URL _is_ the event ID. It's a unique > string that identifies the event, with the added bonus of encoding how to > get the most recent version of the event. > > Implementations are of course going to have some kind of internal ID > field, which will likely form some component of the URL. But the Open511 > API doesn't include any concept of event ID other than the URL, and you > never need any other kind of ID to use the API. > > That said, if this kind of design purity ends up confusing users, it's not > worth it. I don't have any particular problem with doing something like: > > > > mtq.open511.ca/min43104 > > Does that seem friendlier to you? If so, I can discuss this with our other > collaborators and see whether they too prefer adding a field like that. > > — > Reply to this email directly or view it on GitHubhttps://github.com/opennorth/Open511API/issues/45#issuecomment-20164615 > . ## Michael

[Hoedic]

Good point about the <id> in jurisdiction. This field was not there initially and we added it recently. It was added only to ease event filtering by jurisdiction. If we were to keep the resource url as the jurisdiction id, filtering event for jurisdiction would have looked like:

....&jurisdiction=http://my.jurisdiction.gov/api/jurisdictions/mycity.gov/&...

(with all the required encoding) which was a little painful.

Since there is no need to filter anything based on event id (if you want a given event, you have to use the url), we did not add an <id> field for the events.

For the event id, you also have to take into account that this ID has to be unique system wide (when I say system, it's across jurisdictions). Given that open511 allows aggregation from other sources (e.g source A also republishs events from Source B), we have to make sure that ids from source A do not overlap with ids from source B. Which explains why @rhymeswithcycle did an example like :

    <id>mtq.open511.ca/min43104</id>

where the <id> field is the combination of the jurisdiction ID and a sort of internal id for the event... which, in the end, is not that far from the url.

We did our design based on best practices for REST services and trying to reuse as much as possible existing ontologies (atom and gml). Also note that URLs are not fixed. So analyzing the URL to retrieve an internal id is not recommended.

So we are trying to balance "design purity" and ease of implementation.

[mcolynuck]

I think the key point here is that the url has to be unique across all APIs. I was in the mindset that it was unique only within 'that' API understanding that each API may use the same ID. Six of one and half a dozen of the other I suppose.

My resistance has been from the viewpoint of the API consumer (who just wants his ID like he always had it) and as the author of our own API (which will have the data I want to consume). What I lost sight of was that the API does not know, nor should be too concerned with, how the data is ultimately used. Consider me converted ;)

On 28 June 2013 06:38, Stéphane notifications@github.com wrote:

Good point about the in jurisdiction. This field was not there initially and we added it recently. It was added only to ease event filtering by jurisdiction. If we were to keep the resource url as the jurisdiction id, filtering event for jurisdiction would have looked like:

....&jurisdiction=http://my.jurisdiction.gov/api/jurisdictions/mycity.gov/&...

(with all the required encoding) which was a little painful.

Since there is no need to filter anything based on event id (if you want a given event, you have to use the url), we did not add an field for the events.

For the event id, you also have to take into account that this ID has to be unique system wide (when I say system, it's across jurisdictions). Given that open511 allows aggregation from other sources (e.g source A also republishs events from Source B), we have to make sure that ids from source A do not overlap with ids from source B. Which explains why @rhymeswithcycle https://github.com/rhymeswithcycle did an example like :

<id>mtq.open511.ca/min43104</id>

where the field is the combination of the jurisdiction ID and a sort of internal id for the event... which, in the end, is not that far from the url.

We did our design based on best practices for REST services and trying to reuse as much as possible existing ontologies (atom and gml). Also note that URLs are not fixed. So analyzing the URL to retrieve an internal id is not recommended.

So we are trying to balance "design purity" and ease of implementation.

— Reply to this email directly or view it on GitHubhttps://github.com/opennorth/Open511API/issues/45#issuecomment-20188496 .

Michael

[michaelmulley]

(Reopening cause I think this might make using the API more intuitive for many users.)

[michaelmulley]

... and we've added an ID field, as described above, to event resources. I think it's friendlier to users, and it imposes practically no burden on implementors.