Open ArchBlood opened 6 months ago
luke-
commented
6 months ago We need this seperation:
Content API: Provides generic metadata valid for all content types
Post API: Only data relevant for posts (i.e. message)
Poll API: Only data relevant for polls (question, answers, ...)
ArchBlood
commented
6 months ago We need this seperation:
- Content API: Provides generic metadata valid for all content types
- Post API: Only data relevant for posts (i.e. message)
- Poll API: Only data relevant for polls (question, answers, ...)
That is what I had thought as well till I started working on the P/R mentioned;
When using the API we get the information for $post->id, $post->message and ContentDefinitions::getContent($post->content), this last part for $post->content is what is confusing to me, if we use both the Post API and Content API we're creating a duplicate of data unnecessarily, the only real difference I'm seeing is the structure of both APIs when generating a JSON file, one uses the Post model and the other Activity model.
https://github.com/humhub/rest/blob/fd0a0da0fad0a0afa8002b7a9853e85d03bbf6d4/definitions/PostDefinitions.php#L19-L26
I currently see no issues within the Content API as it does exactly what it should do when calling ContentDefinitions::getContent(), but again, here it calls other definitions which can duplicate data and inflate the load time/timeout when trying to download data, what I mean by this is if we were to call all of the definitions we'd create the same data over and over again which shouldn't really be intended.
https://github.com/humhub/rest/blob/fd0a0da0fad0a0afa8002b7a9853e85d03bbf6d4/definitions/ContentDefinitions.php#L24-L33
My thoughts are we should, of course, use the Content API for generic metadata and that is all it should do. Here's an example of what I'm talking about when calling both APIs, both do basically the same thing but are structured differently;
{
"post": [
{
"id": redacted,
"message": "Test",
"content": {
"id": redacted,
"metadata": {
"id": redacted,
"guid": "redacted",
"object_model": "humhub\\modules\\post\\models\\Post",
"object_id": redacted,
"visibility": 1,
"state": 1,
"archived": false,
"hidden": false,
"pinned": false,
"locked_comments": false,
"created_by": {
"id": 1,
"guid": "redacted",
"display_name": "Tony GM",
"url": "https:\/\/domain.com\/u\/archblood\/"
},
"created_at": "2024-01-26 08:56:11",
"updated_by": {
"id": 1,
"guid": "redacted",
"display_name": "Tony GM",
"url": "https:\/\/domain.com\/u\/archblood\/"
},
"updated_at": "2024-01-28 10:51:22",
"scheduled_at": null,
"url": "\/u\/archblood\/post\/post\/view?id=redacted",
"contentcontainer_id": redacted,
"stream_channel": "default"
},
"comments": {
"total": "0",
"latest": []
},
"likes": {
"total": 0
},
"topics": [],
"files": []
}
}
],
"content": [
{
"id": redacted,
"metadata": {
"id": redacted,
"guid": "redacted",
"object_model": "humhub\\modules\\activity\\models\\Activity",
"object_id": redacted,
"visibility": 0,
"state": 1,
"archived": false,
"hidden": false,
"pinned": false,
"locked_comments": false,
"created_by": {
"id": 1,
"guid": "redacted",
"display_name": "Tony GM",
"url": "https:\/\/domain.com\/u\/archblood\/"
},
"created_at": "2024-01-07 04:24:17",
"updated_by": {
"id": 1,
"guid": "redacted",
"display_name": "Tony GM",
"url": "https:\/\/domain.com\/u\/archblood\/"
},
"updated_at": "2024-01-28 23:13:02",
"scheduled_at": null,
"url": "https:\/\/domain.com\/content\/perma?id=redacted",
"contentcontainer_id": redacted,
"stream_channel": "activity"
},
"comments": {
"total": "0",
"latest": []
},
"likes": {
"total": 0
},
"topics": [],
"files": []
}
]
}Sorry, unfortunately I don't quite understand it. The data is structured in the same way.
The reason that the Post API also receives content data is mainly to simplify the REST API and make various REST requests unnecessary.
ArchBlood
commented
6 months ago Sorry, unfortunately I don't quite understand it. The data is structured in the same way.
- Post API contains post information + content data
- Content API only contains content data
The reason that the Post API also receives content data is mainly to simplify the REST API and make various REST requests unnecessary.
Then wouldn't it make more sense to rename the Content API to Metadata API?
luke-
commented
6 months ago Perhaps we can improve the description here. That this API only provides metadata and generic content information such as comments and likes.
ArchBlood
commented
6 months ago Perhaps we can improve the description here. That this API only provides metadata and generic content information such as comments and likes.
Yes, and probably provide this information within PHPDocs more importantly.
From working on https://github.com/humhub-contrib/legal/pull/68 I can see a few issues that can be noted when using the Rest API module definitions, namely some useful and some non-useful.
A number of definitions rely on one another which can be slightly confusing when implementing, Post API relies on Content API when triggering
getPost()so I don't see a real need for the Post API if it just contains the same information as another API, it works but the reliance on another API is very high, I can understand this being done in Content API as this is where most of the data can be generated and retrieved but I'm not understanding why it is needed in Post API when all you should need a$post->idand$post->message, as of right now when using the Post API it pulls all the same information that the Content API does, the Post API should be a simplified version of Content API so not to confuse the person that is using it.