17 Feb 2018 - by 'Maurits van der Schee'
Almost every backend application that is created today has a REST API. And most "serious" applications have a hundred database tables or more. In such case there are two ways to create a consistent REST API: code generation and reflection in runtime. Both methods have upsides and downsides. I have implemented a runtime reflection based REST API before (in PHP) and have now done this again in a Java library.
I have seen many slow and inconsistent REST API's in my career. That's why the ambitions of this library are high:
It all boils down to: you should be tempted to use it on your next OLTP build!
The library is certainly opinionated, so if you disagree with any of the following you should probably look at other tools, such as spring-data-rest.
Primary keys are fields in the record that uniquely identify the record and that do not change. For example: An email address may be unique for a user, but it may be changed, so it does not make a good primary key. You can only guarantee that a value won't change when it does not mean anything. Therefor technical primary keys are the way to go.
If PUT is a full update, then that can never be successfully executed as identity columns (primary keys) may not be updated. If you are leaving out primary keys, then you should be using PATCH (according to the standard). When you are creating a record you may be leaving out values as well, as left out fields have a specific behavior in SQL: during creation they are set to default. When we are updating a record we can also specify the fields to update. So we should either always use PATCH or allow partial updates via PUT. I think the latter makes more sense.
If you want metadata, then you may request it on a separate endpoint. There is really no benefit in sending both in the same request. I'm not saying metadata is useless, on the contrary: There are great initiatives, such as Swagger, that allow you to use the metadata to generate documentation.
This is where the library should really stand out. All features you can dream of should be included. So much that you would get demotivated to "roll your own". A selection of the features I want to implement:
Currently many features are already working and I would invite you to give it a try.