Description

The described routes take care of the creation, status-tracking and deletion of SocialHub Posts.

The only required property of a SocialHub Post is the actual content that should be published, called payload.

There are several optional properties that can be added when desired or necessary.

Most important are the channels, posttypes and networktargets properties which can be thought of filters. If none of these filters are set, a post will be published with the default post types into all available network targets of any channel.
Each of these filter array lists take the unique ID of these configuration objects.

Also important is the contentSourceLink property which should contain an URL to a public content the post belongs to (if there exists any).

To be able to keep track of a post's status without the need of polling, you may use the postStatusCallback property. It must contain an URL to a reachable callback where the current status should be reportet to.

Required for comment synchronization of a post is the postCommentCallback property. To the specified URL-callback it will be reported when new comments are created, updated or deleted on a (social) network.

If desired, posts can also be reliably scheduled to a certain point of time in future to be published by using the scheduled property and specifying a valid ISO8601 date-time value.

Request schema

{
    "description":"Representation of a SocialHub Post entity",
    "type":"object",
    "additionalProperties": false,
    "properties":{
        "channels":{
            "description":"All channels the payload has to be published to if not there post to all channels",
            "type":"array",
            "required":false
        },
        "posttypes":{
            "description":"All posttypes the payload has to be published with, if not there the default one will be used",
            "type":"array",
            "required":false
        },
        "networktargets":{
            "description":"All networks the payload has to be published to if not there post to all networks",
            "type":"array",
            "required":false
        },
        "contentSourceLink":{
            "description":"The URL to the actual content in the source site",
            "type":"string",
            "format":"url",
            "required":false
        },
        "postStatusCallback":{
            "description":"A callback URL where the current status of the post should be reportet to",
            "type":"string",
            "format":"url",
            "required":false
        },
        "postCommentCallback":{
            "description":"A callback URL where comment creation, update and deletion requests should be send to",
            "type":"string",
            "format":"url",
            "required":false
        },
        "scheduled":{
            "description":"Scheduling the publication of the post to a certain point in the future (if not present, published instantly)",
            "type":"string",
            "required":false,
            "format":"date-time" 
        },
        "strict":{
            "description":"Forbids to change the content to be publishable on certain networks (e.g truncate for twitter)",
            "type":"boolean",
            "default":false,
            "required":false
        },
        "failOn":{
            "description":"Whether to fail processing with error when an actual error occurs or even on warnings",
            "type":"string",
            "enum":["warning","error"],
            "default":"error",
            "required":false
        },
        "payload":{
            "description":"The actual content to be published",
            "type":"any",
            "additionalProperties":true,
            "required":true,
            "properties":{}
        }
    }
}

Response schema

{
    "description":"A post-status response / update object",
    "type":"object",
    "additionalProperties": false,
    "properties":{
        "postId":{
            "description":"The postId of the (new) post",
            "type":"string",
            "required":false
        },
        "postStatus":{
            "description":"The current status of the post",
            "type":"string",
            "required":false
        }
    }
}

Possible values of the postStatus property are:

• QUEUED: Post is queued for processing
• SCHEDULED: Post is scheduled scheduled
• PPROCESSED: Post was processed and is going to be published
• FINISHED: Post has been successfully published
• ERROR: There was an error in processing or publishing the post

POST /posts

Creates a new post (see required request schema above).

Simple example post:

{
    "channels":["dutoegnuu0VyQrckgD9KXNaL5Lit0l5u"],
    "contentSourceLink":"http://example.com/abc",
    "payload":{"message": "Look at that", "field-image": "http://example.com/a.jpg"}
}

Example result:

{
    "postId":"7utoegnuu0VyQrckgD9KXNaL5Lit0l5u",
    "postStatus":"QUEUED" 
}

PUT {postStatusCallback}

Updates the status of a post which was send to the API.
This is not a Publisher API route, but a route that would be implemented by the site which created the post.
If given, the SocialHub will make a PUT request to the postStatusCallback-URL specified in the post-data, every time the status of the post changes.

Request schema is the same as the response of a POST /posts request:

{
    "postId":"7utoegnuu0VyQrckgD9KXNaL5Lit0l5u",
    "postStatus":"PROCESSED" 
}

DELETE /posts/{PostId}

Deletes the specified post.