Presenting non-aggressive aggregated data with the JSON API

Question

I am working on an application for which we are exploring the use of jsonapi to describe data in all API responses. It works very well for objects like resources, but we are having problems with the ability to describe report data in a jsonapi-like way.

According to the reports, I refer to aggregated and calculated data on the fly from the basic resource-like data that we store in our database. For example, imagine that we store information about real estate and we have information about houses, apartments and office premises, each of which is related to the location, size of property in square feet, type of property (let it be a house, apartment or office space), and any other relevant property information. Now imagine that we need a report that gets ?group_by[]=location&group_by[]=type , and we want the response to transmit aggregated information about the intersection of these two group_by parameters. Thus, we would get, for example, an object containing the average square foot area of ​​all properties in a given place, also grouped by property type.

 Average Property Sizes (in square feet) Houses Apartments Offices Manhattan 1234.56 234.56 123.45 Cape Coral 456.78 654.32 876.54 Portland 4321.00 987.65 2345.67 

The most resource-like thing we can think of from this data is each cell, but since they are the result of a computed set of more basic data, they do not have a natural identifier. We also thought about delivering them using a billing identifier (perhaps by combining the size identifiers by which their data is grouped, ie "house,34" , where house represents the property type and 34 is the Manhattan location identifier). Each cell will then be associated with a corresponding location record that will be included in the included payload section. Here is an example json file how it looks:

 { "data": [ { "id": "house,123", "type": "report_items", "attributes": { "property_type": "house", "value": 108.75 }, "relationships": { "location": { "data": { "type": "locations", "id": 123 } } } }, { "id": "house,124", "type": "report_items", "attributes": { "property_type": "house", "value": 36.0 }, "relationships": { "location": { "data": { "type": "locations", "id": 124 } } } }, { "id": "house,125", "type": "report_items", "attributes": { "property_type": "house", "value": 1.0 }, "relationships": { "location": { "data": { "type": "locations", "id": 125 } } } }, { "id": "office,123", "type": "report_items", "attributes": { "property_type": "office", "value": 4.0 }, "relationships": { "location": { "data": { "type": "locations", "id": 123 } } } }, { "id": "office,124", "type": "report_items", "attributes": { "property_type": "office", "value": 2.0 }, "relationships": { "location": { "data": { "type": "locations", "id": 124 } } } }, { "id": "apartment,123", "type": "report_items", "attributes": { "property_type": "apartment", "value": 2.0 }, "relationships": { "location": { "data": { "type": "locations", "id": 123 } } } }, { "id": "apartment,125", "type": "report_items", "attributes": { "property_type": "apartment", "value": 4.5 }, "relationships": { "location": { "data": { "type": "locations", "id": 125 } } } }, { "id": "apartment,124", "type": "report_items", "attributes": { "property_type": "apartment", "value": 2.0 }, "relationships": { "location": { "data": { "type": "locations", "id": 124 } } } } ], "included": [ { "type": "locations", "id": "123", "attributes": { "name": "Manhattan" } }, { "type": "locations", "id": "124", "attributes": { "name": "Cape Coral" } }, { "type": "locations", "id": "125", "attributes": { "name": "Portland" } } ] } 

My question is: is this data representation correct in jsonapi? Is jsonapi suitable and / or recommended for data that is not directly mapped to resources? Will it be better to present this data in custom json? I know that not of these questions, there is probably a definite answer, but perhaps there is already some experience in how to approach such scenarios, the pros and cons of trying to make such data suitable for jsonapi, etc. Any comments and help are very much appreciated. Thanks.

PS: I posted this even after some digging on the forum and on the Internet, and these are the only two links I found that say something that resembles what I'm trying to figure out, and I include them here for reference: 1 .- http://discuss.jsonapi.org/t/composite-id-inside-the-resource-object/367/13 2.- http://discuss.jsonapi.org/t/extension-for-chart- graph-data / 408

Answer 1

The general answer is to consider which data is significant enough to guarantee identity on both sides of your API. By this I mean deciding what things you either want to reference later or represent with relationships. The JSON API allows you to define these things as resources and allows you to mix resources with more general JSON for opaque data.

For example, maybe reports , and the parameters and filters that you used to create them deserve to be tracked so that the client can request a fresh view of the same report using id . You might want to poll your server to see which reports are generated.

On the client side, you can submit links from property_type resources for more information about these types of properties.

Or perhaps the results in the report are better represented as a JSON drop in the resource. attributes and meta can contain any JSON values.

In your particular case, your main resource may be of type reports or a report_items array report_items or perhaps even a property_summaries array with relations with property_types and locations .

If you choose more general types of resources, you can generalize the reporting process, but you cannot capture the significance of the data.

If you choose very specific resources for reporting, you will really need to customize each type of report, but you can make meaningful connections between your resources on your client.