Bridge is all grown up. With three developers, we've had to discuss and make decisions about design of the system. Here's what we have so far:
...
We use the following nomenclature for different kinds of identifiers:
| guid | a system generated, globally unique string to identify a record. Even if we change data stores or migrate data, we should be able to continue retrieving objects with this value |
| id/identifier | a user-supplied string that has to be unique within some scope, e.g. study identifier, a string that has to be unique for all studies. We're inconsistent on the user of this even externally, e.g. you'll see id or identifier or even studyKey in documentation. |
| key | a unique string (within some scope) made up of other parts, I don't know if any of these are exposed to users. Usually we separate with a colon. |
Spring
We use spring to wire up our server. We generally use the @Component, @Autowired, or @Resource annotations to minimize the amount of boilerplate code that needs to be written. Example: https://github.com/Sage-Bionetworks/BridgePF/blob/develop/app/org/sagebionetworks/bridge/services/UploadValidationService.java
...
Because no one ever updates them, don't put a serial version ID in a class file. Annotate the class with the annotation @SuppressWarnings("serial") and let the compiler generate it.
Timestamps ideally are stored as ISO 8601 strings (because these preserve the time zone submitted by the user). If you need to query against the value, however, then it needs to be a Long (not the long primitive) or it'll get serialized to users as "1970-01-01T00:00:00.000Z" when not set (or null). There are cases where we're returning times to a user in a different timezone than the one they used to submit the timestamp in the first place, for this reason. For these Long values we have a custom serializer/deserializer for Jackson to convert to an ISO 8601 value in the JSON.
Documentation of fields in our Swagger API definition
There are some semantics in Swagger that are confusing, particularly in terms of when and how they apply (when an object is submitted on creation, when it is returned from the server, etc.). Here is how we are using some key property fields:
...