missing toJson() in ResourceData?

[frank06]

I was trying to serialize via Document(ResourceData(resourceObj)).toJson(); but I ended up with a plain ResourceObject inside a JSON property.

Shouldn't this line be calling toJson()?

https://github.com/f3ath/json-api-dart/blob/master/lib/src/document/resource_data.dart#L35

(And thank you for the fantastic library!)

[f3ath]

Thanks for your kind words. To be precise, toJson() does not serialize objects. Its purpose is to return a serializable representation. And since ResourceObject has its own toJson() method the resulting object is serializable. So the whole thing works as intended, it is not necessary to call toJson(), Dart's json serializer will do it for you. But we still can add that call to improve performance slightly. Feel free to open a PR, I'll gladly accept it.

[f3ath]

If you need to serialize it, pass it to jsonEncode().

[frank06]

Thanks! I just sent a PR.

I understand dart:convert will internally serialize that to proper JSON, but I'm feeding this "JSON" (Map<String, dynamic) to a hook where it can be further manipulated before being sent off to json.encode.

[f3ath]

@frank06 would you mind sharing which manipulations you do? I consider the toJson() methods an implementation detail which should not be relied upon. If there is a need in post processing, it should be done explicitly through the library's public contract to avoid possible breaks in the future.

[frank06]

I thought toJson() methods were public API. I am actually using json-api-dart precisely because it allows me to serialize from/to JSON:API.

I have the following situation where the library does internal serialization (model to JSON:API) but gives its clients a chance to massage that data before converting to a JSON string.

ResourceObject _obj = internalSerialize(model);
Map<String, dynamic> _json = serialize(Document(ResourceData(_obj)).toJson());
// ...
json.encode(_json);

(serialize is abstract here)

[f3ath]

Yes, toJson() is indeed a part of public API. But the contract this method expresses is literally the following: "an instance of Document, if passed to jsonEncode() or json.encode(), will produce a valid JSON:API payload". That's it. There is no guarantee that whatever my toJson() returns will stay the same as long as Dart's json encoding system can handle instances of Document correctly. That's why I'm saying that the method itself is rather an implementation detail, but not a part of my commitment. That's why there is no direct calls to toJson() in the tests (if there are, it's a bug and should be fixed) - I test encoding indirectly by passing instances of encodable classes to jsonEncode(). If tomorrow Dart decides to change how it does json encoding, all the toJson() may go away. It is just a pure coincidence that you can call toJson() directly and understand the returned values.

Hope that explains my point. So if you tell me more about that post-processing you do, I may be able to incorporate your (and probably other people's) needs in the library the way that it is clearly expressed in the contract and in the tests.

[f3ath]

I mean, from the business logic standpoint, what is that post-processing? If you change the data in a JSON:API compatible manner, let's add that logic to the library. If it's logging/analysis, can it be done via onHttpCall parameter in the client?

[frank06]

Thank you for the explanation.

from the business logic standpoint, what is that post-processing?

My library uses JSON:API as internal format. Clients operating with JSON:API can use it directly. Clients who use other flavors of JSON can still use it as long as they override serialize and deserialize to convert their JSON to JSON:API.

This is working already, I have a mixin that processes JSON from https://jsonplaceholder.typicode.com/ to/from JSON:API so that it works with my library. I will likely open source it in the coming weeks and I'll show you.

So, no, this post-processing is neither logging/analysis nor would it belong to json-api-dart.

the method itself is rather an implementation detail, but not a part of my commitment

Totally understood. If upgrading json-api-dart starts causing failures in my library's tests, I will be forced to find a workaround or eventually a replacement.

[f3ath]

Closing as solved.