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:
| Table of Contents |
|---|
Database
Make sure we have SQL indices on any field we query on.
For all foreign keys, specify ON DELETE CASCADE and ON UPDATE CASCADE.
REST Endpoints
We're following a resource-oriented structure for the URLs that follows this pattern (assume the resource is orchards):
...
When an endpoint includes an identifier, and the JSON that is submitted to that URL includes a different identifier, we want to throw an exception (TODO: What exception I wonder).
Identifiers
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
...
/** Service handler for upload validation. This is configured by Spring. */
@Autowired
final void setUploadValidationService(UploadValidationService uploadValidationService) {
this.uploadValidationService = uploadValidationService;
}Serialization
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.
...