Object Identifiers
DbIds
All objects represented in BrAPI have a xxxDbId
field. This field
represents a primary key which will uniquely identify that object
within the database being queried. It is NOT guaranteed to be unique
across multiple systems, though it could be. DbIds should primarily be
used to link data together within a system.
For example, in a given call, an Observation Unit object is returned
with the studyDbId
. In a subsequent call to the same system, you
should be able to retrieve the Study Object directly based on the
studyDbId
.
DbIds Special Case
There was a special case raised in GitHub Issue #85 where the DbId
string was a URL (a DOI url in this specific case, but any url will have
the same problem). URLs generally contains the /
character which
makes them difficult to use as parts of the path in a REST call.
Recommendation: If possible, avoid using URLs as DbIds. There are other fields available for communicating a variety of URLs to a client, reserve the DbId field for a convenient primary key for linking to other objects.
If you must use a URL as a DbId, you must encode it in some way to hide the slashes. Your system will need to accept the encoded string in a request and decode it before querying the database. Likewise, when responding to a request, your system will need to retrieve the URL from the database and encode it before returning. The specific encoding schema doesn’t matter, as long as it produces consistent results within your system. GitHub Issue #85 describes a double URL symbol encoding scheme which works.
Example: `%252F` is decoded as the slash character
.../brapi/v1/germplasm/https%253A%252F%252Fdoi.org%252F10.15454%252F1.4489666216568333E1
Hexadecimal or Base64 encoding are other good options, where the URL becomes an alphanumeric value without slashes. Encoding and decoding this way
is easy and fast, though the value of the DbId
will lose meaning to any human readers.
Example: The DOI is hex encoded
.../brapi/v1/germplasm/68747470733A2F2F646F692E6F72672F31302E31353435342F312E343438393636363231363536383333334531
Example: The DOI is base64 encoded
.../brapi/v1/germplasm/aHR0cHM6Ly9kb2kub3JnLzEwLjE1NDU0LzEuNDQ4OTY2NjIxNjU2ODMzM0Ux
PUIs
Several BrAPI entities have a xxxPUI
field for a Permanent
Unique Identifier. This is meant to be a global identifier
shared across different data sources. PUIs usually take the form of a
URI, with a combination of identifying authority and unique identity
value. For example, the Digital Object Identifier (DOI) system is often used to assign PUIs.
Unlike DbIds, PUIs are never used in BrAPI paths, so there is no problem
if a PUI contains slashes. In several cases, PUIs can be used as query
parameters, so it can be helpful to use the encoding %2F
to replace
an slash characters in URL query parameters.
External References
Every BrAPI V2 entity has a list of externalReferences
. These are
meant to record additional identifiers for a data object, usually
originating from other tools and systems. This can assist with linking
to different systems, without altering the DbIds or PUIs. A particularly
important use case for using externalReferences
comes from uploading
data to a database. When uploading data, the original DbId is not
preserved by default because it is assumed that each system will assign
a new primary key for new data. The externalReferences
allow the
originating system to preserve a DbId while uploading. This is often
very useful for maintaining links between data.
Names
Most objects represented in BrAPI have a xxxName
field. This field
is meant to be a short, human readable summary of the object. It is NOT
guaranteed to be unique in ANY WAY. Names are a convenient way to
interact with users by printing on a screen or searching. Names may be
created by a human user or generated automatically by some concatenation
of other data points. Name fields should not be used to pass any data
other than the intended human readable reference string. For example,
the name Field_Trial_abc123
should never be parsed to extract
abc123
as a usable DbId or piece of data.