Come up with a unified record format for endpoints that combine different records.

[tburry]

Some endpoints return multiple types of records and we should make sure that API clients can look at them without too much processing. Here are my thoughts:

Row Identification

The row needs to identify the type of record in it. For this we need the following fields:

• recordType
• recordID

Common Fields

Common fields that tables already have are left alone.

• name
• body, format
• insertUserID, dateInserted, insertIPAddress
• updateUserID, dateUpdated, updateIPAddress

Other Fields

Each record should leave its own fields in the row so that the client can do something with that row. The fields for each row should be the same as those offered by their own GET endpoints. This means the primary key will be returned twice.

I suspect for this to work well there should be an interface that the various API controllers can implement to fetch their records and join them into a dataset with just recordType and recordID.

[linc]

@initvector Believe this is where some of our meeting notes should go.

[initvector]

The original issue outlined the desired format, pretty well, already. Here, I am attempting to be more explicit and succinct in what's already been stated, in addition to making a couple minor suggestions for improvement.

Proposed Solution

1. API endpoints returning datasets (multidimensional arrays) containing different types of resources (e.g. search) will need to include two additional fields for each row:
   1. recordType: The type of resource (e.g. discussion).
   2. recordID: The unique ID of the resource row.
2. The unique ID field for a row should not be removed when recordID is added. For example, commentID and recordID are valid on a single row, simultaneously.
3. "Common" fields should be used as much as possible. The following is a definitive list of current common fields: name, body, format, insertUserID, dateInserted, insertIPAddress, updateUserID, dateUpdated, updateIPAddress, attributes.
4. If a resource has a field that is analogous to a common field, it should populate that field with its value. For example, if a row has a "Text" field and no "Body" field, and the purpose is the same, the "Body" field should be added with the contents of "Text". This would be done so the data is easily consumed.
5. No further modification of the rows is necessary. Various fields, unique to each resource type, remain in the row as part of the full dataset.
6. Add an interface with a method for expanding a dataset of rows with only recordType and recordID.
   1. This interface method will be implemented by resource API controllers.
   2. It will take the barebones dataset and expand rows matching their resource type.
   3. The expanded fields will be limited to those returned by a default GET/id request to the endpoint.

[tburry]

This looks good. I added "attributes" as another list of fields. I think this would be a good page in our writing APIs documentation as a separate page. This would have to change from a numbered list to a doc page and I would add the definitive list of fields into a proper list under its own heading for easy scanning.

[initvector]

An issue for the docs page has been added: vanilla/docs#111

An implementation will be added as part of #5535