Difference between Post API & Content API

[ArchBlood]

From working on humhub/legal#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->id and $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.

[luke-]

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]

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;

Post API

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.

rest/definitions/PostDefinitions.php

Lines 19 to 26 in fd0a0da

	public static function getPost(Post $post)
	{
	return [
	'id' => $post->id,
	'message' => $post->message,
	'content' => ContentDefinitions::getContent($post->content)
	];
	}

Content API

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.

rest/definitions/ContentDefinitions.php

Lines 24 to 33 in fd0a0da

	public static function getContent($content)
	{
	return [
	'id' => $content->id,
	'metadata' => static::getContentMetadata($content),
	'comments' => CommentDefinitions::getCommentsSummary($content),
	'likes' => LikeDefinitions::getLikesSummary($content),
	'topics' => static::getTopics($content),
	'files' => FileDefinitions::getFiles($content),
	];

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": []
        }
    ]
}

[luke-]

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.

[ArchBlood]

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-]

Perhaps we can improve the description here. That this API only provides metadata and generic content information such as comments and likes.

[ArchBlood]

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.