1

So, according to official documentation sample, responses from OneNote might have the following structure:

{
  value:{the content we requested},
  error:{error if exists with warnings inside if exist},
  @api.diagnostics:{warnings if exist}
}

But, if the response body contains not JSON array but JSON Object, the response would be the following

{
  Here would be entity, representing the content we requested
}

So, my question is next: is there a way to unify responses from OneNote API, because current response structure violates its contract.

As i have an ability to change my request module using interceptors so the output will look like I need, this seems to be a dirty workaround, so I'd like to see an official information on this issue.

Игорь Комаров
  • 105
  • 1
  • 7

2 Answers2

1

Actually, there is no way except one dirty workaround mentioned above. To refactor the OneNote (and other common services) API one should implements either interceptor or something like servlet, that would transfer all of the unknown properties, that seem to be the entitiy's properties to the new root json property making it similar to the format of response for the collection representation of data. So, unless the API would be refactored to match good style nothing could be done. Hope someone from Microsoft would see this and leave a comment on why the API implementation is requiring server-side work on client

Игорь Комаров
  • 105
  • 1
  • 7
0

http://www.odata.org/getting-started/basic-tutorial/

The OneNote API is an OData API - which means it conforms to the OData standard, where arrays are returned as part of the value property.

While entities in arrays are returned in the "value" property:

{ value:[element1, element2, ...], }

And specific entities aren't

{ element1 }

This is relatively easy to solve in any language that supports generics by using a container class for odata payloads, like:

class ODataPayload<T>{ Public IList<T> Values {get; set;} }

This way you could parse "T" when getting a single entity and ODataPayload when getting multiple.

Or you could also use something like http://json2csharp.com/ to generate your parsing classes.

Note that errors will only be returned with 4xx ad 5xx status codes. Any 2xx status code should give you an entity.

Jorge Aguirre
  • 2,787
  • 3
  • 20
  • 27
  • Thank you for the answer, but the thing you said is what I said I know. The question was the following - how to separate errors and warnings from the response data (actual data we wanted to get). As for now, I am using Google Gson for customizing the deserialization process as a low-level interceptor in my response parse model. So, there, I perform moving extra fields within the root json except "error" and "@api.diagnostics" if "value" not exists to new element in root called "value", so the answer from api does not differ depending on response data type. But this is a really dirty workaround – Игорь Комаров Feb 24 '17 at 10:36
  • Being more concrete: entity should never contain an error, as an error should never contain an entity. This is architectural error. As if we say in terms of clean architecture - the entity layer should contain universal response format, that INCLUDES as properties response data, error description if exists and other special fields, that would be common for EVERY response. Otherwise, there is a possibility of misunderstanding, when an entity would contain some field with name equals to common response part error (e.g. entity containing prop "error" and general response containing prop "error") – Игорь Комаров Feb 24 '17 at 10:51
  • Updated my response. Errors will only be returned on 4xx and 5xx status codes, entities will only be returned in 2xx status codes. – Jorge Aguirre Feb 25 '17 at 02:51
  • You tell me the things I know just in case that's what everyone more-less familiar with http knows. Obviously 4xx and 5xx codes are signs of an error, but, dude, my application don't know that, and more - it should not know this. It expects data, handles errors and warnings. Putting entity within the root is a bad practice. Anyway, now I am just moving non-stable (e.g. props except error, @api.diagnostics and value) under the value tag and things go right. Pity that OneNote developer's don't mind their api is violating the general contract. – Игорь Комаров Feb 25 '17 at 12:31