To provide guarantees about the interfaces of the objects returned by the API, we use a models for the responses and check the types at runtime (as of v0.0.14).
We would like this model to be relatively strict to detect API changes as quickly as possible and provide a faithful documentation of the data. This strict model combined with thrown errors on failure makes it currently hard to use the library in the face of unexpected responses due to changes.
A quick fix was merged to ignore extra keys.
To improve the situation, here is the approach I'd like to follow:
Step 1: Improve the error messages to be more actionable. The missing keys, invalid types and deserialization errors should better identify their position in the JSON document and the value causing the error. The deserialization should try to collect most of the errors instead of aborting on the first error (so we can have a shorter dev/test cycle). I wrote the deserialization and error libraries to support this kind of use case so this should be done relatively quickly.
Step 2: Ensure that consumers can override the deserialization either by passing a handler function or having an a useful error object exposing the JSON response. Both solutions could be mixed (handler to completely override the deserializer and error with data just to recover from unexpected responses). Another solution that may be cleaner could be to add a function exposing the raw response (something like .getContacts and .rawGetContacts).
Step 3: On error, issue a warning and automatically recover from the error. This kind of approach would work by having a strict model with extra hypothesis and a loose model that is guaranteed to work. We would first try to apply the strict model and fallback to the looser model. At this step, we would have a safe way to extend our model by pushing hypothesis to the strict model, trying it in real world situation and then updating the base model. It should be possible to handle warnings programmatically (it should not be hard coded as console.warn(...))
Step 4: Error report generation. To properly test the strict model, we need to run it in real-world situations and then get the feedback. We should provide helpers to handle the warnings and help collecting them. The most important part would be to sanitize the data by trying to remove any personal information so the consumer can post the report without having to sanitize it itself. Beyond that, helpful error messages recommending to submit warnings to this repo should help.
This kind of support will be rolled out over multiple versions but I wanted to write down the general direction for this part of the lib.
To provide guarantees about the interfaces of the objects returned by the API, we use a models for the responses and check the types at runtime (as of
v0.0.14). We would like this model to be relatively strict to detect API changes as quickly as possible and provide a faithful documentation of the data. This strict model combined with thrown errors on failure makes it currently hard to use the library in the face of unexpected responses due to changes. A quick fix was merged to ignore extra keys.To improve the situation, here is the approach I'd like to follow:
.getContactsand.rawGetContacts).console.warn(...))This kind of support will be rolled out over multiple versions but I wanted to write down the general direction for this part of the lib.