task: improve docs for custom persistence options #7
Conversation
README.md
Outdated
| public class Book : IIdentifiable<string> | ||
| { | ||
| // If Id=null generate a random string ID using the MongoDB driver | ||
| [BsonId(IdGenerator = typeof(StringObjectIdGenerator))] |
There was a problem hiding this comment.
There was a problem hiding this comment.
The default of BsonType.ObjectId may be sensible as it is the most performant in MongoDB because it is the binary representation.
There was a problem hiding this comment.
Good to know, then I think we should leave that the default.
README.md
Outdated
| Using `StringObjectIdGenerator` above could then be combined with `AllowClientGeneratedIds` JsonApi setting in `Startup.ConfigureServices` so that IDs can be generated on the client, and will be auto-assigned server side if not provided providing a flexible string based id for the `Book` resource: | ||
|
|
||
| ```cs | ||
| services.AddJsonApi(options => { | ||
| // Allow us to POST books with already assigned IDs! | ||
| options.AllowClientGeneratedIds = true; | ||
| }, resources: builder => | ||
| { | ||
| builder.Add<Book, string>(); | ||
| }); | ||
| services.AddJsonApiMongoDb(); | ||
|
|
||
| services.AddResourceRepository<MongoDbRepository<Book, string>>(); | ||
| ``` | ||
|
|
There was a problem hiding this comment.
I think this is basic JsonApiDotNetCore functionality, which is already documented at https://www.jsonapi.net/usage/options.html#client-generated-ids. I don't see why it needs to be mentioned here, or am I missing something that makes this work differently for MongoDB that requires explanation? Note we have MongoDB-tests for this and all seem to work fine without any special handling.
There was a problem hiding this comment.
The combination of mongoDB features (string ids generated server side) and json api features (optional client side id generation) working in tandem was hard to discover for me and took me a few passes to figure out which was why I was offering some docs up to save others the same hassle but accept what you say.
I think it is MongoDB specific because the library is defaulted to the (performant) binary object id. If you are trying to do client side id generation with AllowClientGeneratedIds then users (me!) may assume they can pass any string id since that is how the API appears. However, in reality the API requires you to pass a 12 byte unique generated object id, and throws an non-obvious exception if you just pass something like "123".
Using mongoDB StringObjectIdGenerator and json:api AllowClientGeneratedIds are a nice fit together in the document db ecosystem because it is common to have client-assigned document random string keys as the default that can be overridden with a unique string if I know the id I want to assign. This differs from relational SQL ecosystem where auto-increment database-assigned ids are the default, and client side key assignment is the exception.
There was a problem hiding this comment.
Makes sense. But then we should have tests backing that scenario, if we're going to advise on doing that. Can you add some? They would demonstrate using the fluent mapping overrides too, which is nice.
|
Thanks for the useful feedback, please re-review - have tweaked the docs based on the comments. |
|
Superseded by #14. |
Small update to the readme