Review API-Guidelines: UUID as identifier

[cgendreau]

All database identifiers should be numerical based since it's efficient and easier to manage at the database level. Even if there is no issue about leaking business information we will still expose UUID instead of the database key in the API. This will give us more flexibility at the database level while reducing potential issues with API users iterating over ids or using a wrong set of ids. Based on the “Inter-module foreign key” module, UUID’s will help detect wrong linkages by making it almost impossible to reuse a key of the wrong resource. Numerical id’s can be reused in different resources (even if this can be solved by using a global sequence) while UUID are more likely to be unique across the system.

This will/should not prevent resources to get a DOI assigned.

[cgendreau]

Actionable, long-term stable and semantic web compatible identifiers for access to biological collection objects:
https://dx.doi.org/10.1093/database/bax003

[cgendreau]

The suggestion from the "Actionable, long-term stable and semantic web compatible identifiers for access to biological collection objects" paper to use HTTP URIs looks effective and quite simply to explain and implement.

The web domains owned and controlled by the respective institutions ensure the global uniqueness of the identifiers and thus, the local object identifiers only need to be unique within each institution's scope which all Institutions are capable to achieve.

Anton Güntsch, Roger Hyam, Gregor Hagedorn, Simon Chagnoux, Dominik Röpert, Ana Casino, Gabi Droege, Falko Glöckler, Karsten Gödderz, Quentin Groom, Jana Hoffmann, Ayco Holleman, Matúš Kempa, Hanna Koivula, Karol Marhold, Nicky Nicolson, Vincent S. Smith, Dagmar Triebel, Actionable, long-term stable and semantic web compatible identifiers for access to biological collection objects, Database, Volume 2017, 2017, bax003, https://doi.org/10.1093/database/bax003

[cgendreau]

Suggestion for the API guidelines:

• Use HTTPS URIs as described in the paper (even if a record can't be publicly resolvable (e.g. sensitive information) it should get one)
• Specify uniqueness of the local object identifier with a suggestion for uuid with its advantages

[jdobber]

Just for clarification, when using UUIDs then we should use variant 1 (date-time and MAC address).
In Python you can get a new UUID like this import uuid; uuid.uuid1().

See also: https://en.wikipedia.org/wiki/Universally_unique_identifier

[cgendreau]

Yes, that should be clarified. Actually the current suggestion was Variant 5.
https://github.com/DINA-Web/collection-specs/issues/13

[dshorthouse]

Some background on decision to use UUIDv5 from @dimus http://globalnames.org/news/2015/05/31/gn-uuid-0-5-0/. Agree with decision to use v5 because they are independently repeatable so long as all parties agree on namespace. Suggest dina-project.net as that namespace.

[cgendreau]

I see the advantages of v5 when assigning uuid for scientific names but it`s unclear to me the advantage of using v5 vs v4 for assigning uuid when a local identifier is used. Maybe I missed something but it could be wrong if 2 implementations would decide to use a primary key as local identifier. Since we would share the same namespace we would end up with the same identifier for 2 completely different entries. Unless the idea would be to use different namespace per institution?

[dshorthouse]

@cgendreau Agree. Will have to put some thought into the reasons why you want to assign a UUID to something. If the primary reasons are to uniquely identify a predominantly string-based entity AND to resolve that identity among and between organizations then a publicly-exposed UUID v5 makes some sense. If these are not the goals, then we'd have to question why we'd want to bother with the overhead when a local, incrementing primary key is far better.