OBIP-0004: Posts

[drwasho]

OBIP-0004: Posts

Proposal: https://github.com/OpenBazaar/obips/blob/master/obip-0004.md
Author: @drwasho

  OBIP: 4
  Title: Posts
  Author: Dr Washington Y. Sanchez
  Status: Draft
  Type: Standards Track
  Created: 2017-08-27

Abstract

• This OBIP describes the addition of a new type of content that can be published and shared on the network by users: posts
• Posts enable a user to publish written content that can be viewed by other users visiting their store or via third party search
• Posts can be used for market-related activities such as: advertising listings, announce store updates, publish a new coupon for a special offer etc
• Moreover, posts can also be used for non-market activities and serve as a platform for censorship-resistant expression on the network, encouraging non-vendors to regularly use the network

Motivation

OpenBazaar has limited tools for Vendors to engage with potential customers. Engagement can be in the form of advertising a listing, announcing a store update, brand-building, announcing special offers or coupons for a sale to name a few. Users in general can also benefit from these tools by blogging interesting items they have seen on the network, and driving sales for Vendors (i.e. OB influencers).

Aside from side-channels (i.e. off the OpenBazaar network), Vendors can only communicate to potential buyers via the About section of their profile, or via direct message. The About section is limited in form and function, and its history is not traversable. Direct message is excellent for one-on-one communication, but it can only be initiated by a user visiting the store.

What is required is a means for Vendors to publish a blog-style post that users can view when visiting their store.

Requirements

Posts allow a Vendor to upload a message or image in a dedicate space in their store. Posts have traversable history, designed for one-way communication from the Vendor to users. The purpose of posts is to inform visitors of any content they feel necessary to drive sales and/or engage with users (i.e. announcements, brand building, promotions, coupons etc).

User Stories

Role: Publisher

A 'publisher' is a vendor or user that is publishing a post on their node for other users to consume.

1. As a Publisher, I can post a message {text, image} that is displayed in my store.
2. As a Publisher, I can edit a message that is displayed in my store.
3. As a Publisher, I can delete a message this is displayed in my store.
4. As a Publisher, I can traverse a history of messages in my store.

Role: User

1. As a user, I can read a message {text and/or image} posted by a Publisher.
2. As a user, I can traverse a history of messages {text and/or image} posted by a Publisher.

Specification

A post should allow the publisher to include:

1. A short title (max. 280 characters)
   • The title field can be used as a title for a long-form post, or as a microblog post in itself (i.e. tweet-style).
2. A long-form post (max. 50,000 characters)
   • This field is used for blog-style posts
3. Images
   • An array of up to 30 images can be attached to the post
4. Tags
   • An array of up to 40 tags
5. A timestamp

All posts need to be digitally signed to establish authenticity, and will include a slug for IPNS resolution so the publisher can edit their post.

Protobuf

The protobuf spec:

syntax = "proto3";
option go_package = "pb";


import "google/protobuf/timestamp.proto";
import "contracts.proto";

message Post {
    string slug                         = 1;
    ID vendorID                         = 2;
    string title                        = 3;
    string longForm                     = 4;
    repeated Image images               = 5;
    repeated string tags                = 6;
    google.protobuf.Timestamp timestamp = 7;

    message Image {
        string filename = 1;
        string original = 2;
        string large    = 3;
        string medium   = 4;
        string small    = 5;
        string tiny     = 6;
    }
}

message SignedPost {
    Post post           = 1;
    string hash         = 2;
    bytes signature     = 3;
}

API

We propose that OpenBazaar server-node implementations support the following endpoints:

1. GET /ob/posts
2. GET /ob/post
3. POST /ob/post
4. PUT /ob/post
5. DELETE /ob/post

GET ob/posts

Returns an array of posts from the user or a peer (i.e. /ob/posts/:peerId):

[
    {
        "hash": "zb2rhdrJUgp17bvjnEW98s9C2eToZHep1eh5i7SBp9jhBpREA",
        "images": [
            {
                "medium": "zb2rhaFhqziCWk1zo5tMRxQEUchfvJFaGG4DY1anEoR4GnYrN",
                "small": "zb2rhbDCeEiTTunugWPaRRKFCfNKUaB7aCR53nrPnMa9usZXY",
                "tiny": "zb2rhgqJDbshwAgPjs7X2h4mDm3V3BpLbp4tFGqkg1LNkg9yV"
            },
            {
                "medium": "zb2rhY4sqZehNgKD7ehxHiG7z3wnpKZEeNccWxrfx1GmAckxy",
                "small": "zb2rhhMRWCb5ozMdez8JePnZnh9WRxyTCJVNk7CfLNVVaUmhz",
                "tiny": "zb2rhmxApBVCHh426vnYSJGSDH4KpKpqKyvY2CAWmaiuHd8tZ"
            }
        ],
        "slug": "multiimagetest",
        "tags": [
            "zb2rhXoKEJtXxB5pcxhmcLu1aCCY3MRHR1Vc4tSJMyzPy8KJv",
            "#freeWynona"
        ],
        "timestamp": "2017-10-05T00:13:53.892275067Z",
        "title": "multiimagetest"
    }
]

GET ob/post

Returns an individual post from the user or a peer (i.e. /ob/post/:peerId/:slug_or_hash):

{
    "post": {
        "slug": "multiimagetest",
        "vendorID": {
            "peerID": "QmVdst57mJuW8Tr9owADqWmirY5Gao9zZMnbbL4WavKJvB",
            "handle": "",
            "pubkeys": {
                "identity": "CAESIEokc1r9Wfe4IyqA9P/56dO+5W1Hv9eOi2PXdUBDUf5X",
                "bitcoin": "AjjghznFUNeAkgmEdKYOESzj+PXFvVHUv+jbNWWQKkwG"
            },
            "bitcoinSig": "MEQCIAaKg1Cr676NVo7dz1KibSvvhjyrAXQceYakKwYR13+oAiBmAWqIyTWMuMPeVItwPzS1N2SDYeR5H4cD+uxGv1AghQ=="
        },
        "title": "multiimagetest",
        "longForm": "This is a test post dawg.",
        "images": [
            {
                "filename": "cat",
                "original": "zb2rhe2o6WbHqcER5VUKsMUbQrmpCC6ihg8qZ4JS9wVgKz9wm",
                "large": "zb2rhmBUB9i7UkfmeD3obJYK3FFS5K8N8QHaUanG8UWLVBHiY",
                "medium": "zb2rhaFhqziCWk1zo5tMRxQEUchfvJFaGG4DY1anEoR4GnYrN",
                "small": "zb2rhbDCeEiTTunugWPaRRKFCfNKUaB7aCR53nrPnMa9usZXY",
                "tiny": "zb2rhgqJDbshwAgPjs7X2h4mDm3V3BpLbp4tFGqkg1LNkg9yV"
            },
            {
                "filename": "random",
                "original": "zdj7Wazpqc5dGZ9yyKweKGjkGF3mAj5cjrWSV3QisHU34UsaQ",
                "large": "zb2rhemVicsnTAo454S6Cdq2Ct677B47ArbQ7AqNtWYWUbvBQ",
                "medium": "zb2rhY4sqZehNgKD7ehxHiG7z3wnpKZEeNccWxrfx1GmAckxy",
                "small": "zb2rhhMRWCb5ozMdez8JePnZnh9WRxyTCJVNk7CfLNVVaUmhz",
                "tiny": "zb2rhmxApBVCHh426vnYSJGSDH4KpKpqKyvY2CAWmaiuHd8tZ"
            }
        ],
        "tags": [
            "zb2rhXoKEJtXxB5pcxhmcLu1aCCY3MRHR1Vc4tSJMyzPy8KJv",
            "#freeWynona"
        ],
        "timestamp": "2017-10-05T00:13:53.892275067Z"
    },
    "hash": "zb2rhdrJUgp17bvjnEW98s9C2eToZHep1eh5i7SBp9jhBpREA",
    "signature": "evhmoAw3S/Qx3lmTStd0esnhPjwgWCfRncpGltyLjW3wPG7Gh8kd4uRSsS+LwoPMpVVvibLuIDi0WwyfsrkODA=="
}

POST /ob/post

Creates a new post:

{
	"title": "multiimagetest-4",
	"longForm": "This is a test post dawg.",
	"images": [{
			"filename": "cat",
			"large": "zb2rhmBUB9i7UkfmeD3obJYK3FFS5K8N8QHaUanG8UWLVBHiY",
			"medium": "zb2rhaFhqziCWk1zo5tMRxQEUchfvJFaGG4DY1anEoR4GnYrN",
			"original": "zb2rhe2o6WbHqcER5VUKsMUbQrmpCC6ihg8qZ4JS9wVgKz9wm",
			"small": "zb2rhbDCeEiTTunugWPaRRKFCfNKUaB7aCR53nrPnMa9usZXY",
			"tiny": "zb2rhgqJDbshwAgPjs7X2h4mDm3V3BpLbp4tFGqkg1LNkg9yV"
		},
		{
			"filename": "random",
			"tiny": "zb2rhmxApBVCHh426vnYSJGSDH4KpKpqKyvY2CAWmaiuHd8tZ",
			"small": "zb2rhhMRWCb5ozMdez8JePnZnh9WRxyTCJVNk7CfLNVVaUmhz",
			"medium": "zb2rhY4sqZehNgKD7ehxHiG7z3wnpKZEeNccWxrfx1GmAckxy",
			"original": "zdj7Wazpqc5dGZ9yyKweKGjkGF3mAj5cjrWSV3QisHU34UsaQ",
			"large": "zb2rhemVicsnTAo454S6Cdq2Ct677B47ArbQ7AqNtWYWUbvBQ"
		}
	],
	"tags": [
		"zb2rhXoKEJtXxB5pcxhmcLu1aCCY3MRHR1Vc4tSJMyzPy8KJv",
		"#freeWynona"
	]
}

PUT /ob/post

Edits an existing post:

{
	"slug": "multiimagetest4",
    "title": "multiimagetest-4",
	"longForm": "This is a test post yo.",
	"images": [{
			"filename": "cat",
			"large": "zb2rhmBUB9i7UkfmeD3obJYK3FFS5K8N8QHaUanG8UWLVBHiY",
			"medium": "zb2rhaFhqziCWk1zo5tMRxQEUchfvJFaGG4DY1anEoR4GnYrN",
			"original": "zb2rhe2o6WbHqcER5VUKsMUbQrmpCC6ihg8qZ4JS9wVgKz9wm",
			"small": "zb2rhbDCeEiTTunugWPaRRKFCfNKUaB7aCR53nrPnMa9usZXY",
			"tiny": "zb2rhgqJDbshwAgPjs7X2h4mDm3V3BpLbp4tFGqkg1LNkg9yV"
		},
		{
			"filename": "random",
			"tiny": "zb2rhmxApBVCHh426vnYSJGSDH4KpKpqKyvY2CAWmaiuHd8tZ",
			"small": "zb2rhhMRWCb5ozMdez8JePnZnh9WRxyTCJVNk7CfLNVVaUmhz",
			"medium": "zb2rhY4sqZehNgKD7ehxHiG7z3wnpKZEeNccWxrfx1GmAckxy",
			"original": "zdj7Wazpqc5dGZ9yyKweKGjkGF3mAj5cjrWSV3QisHU34UsaQ",
			"large": "zb2rhemVicsnTAo454S6Cdq2Ct677B47ArbQ7AqNtWYWUbvBQ"
		}
	],
	"tags": [
		"zb2rhXoKEJtXxB5pcxhmcLu1aCCY3MRHR1Vc4tSJMyzPy8KJv",
		"#freeWynona"
	]
}

DELETE /ob/post

Deletes an existing post: /ob/posts/:slug_or_hash

Rationale

Advantages

1. Allows for users to engage with visitors and promote sales
2. Creates basic tools for an influencer and affiliate program
3. It is a platform for censorship-resistant expression

Disadvantages

• index.json file can get bloated if there are a lot of posts
  • This could potentially be mitigated by only storing hashes of the post in an array

Backwards Compatibility

This OBIP extends the protocol and creates a collection of new APIs, as well as a new directory to store posts. This means that non-upgraded nodes will not be able to fulfil API calls for posts if requested. The server will return a standard error for unrecognised API calls.

Posts do not alter the existing database or API calls, so disruption to clients should be minimal. As a result, clients can choose to support this feature - if at all - at their leisure.

Reference Implementation

https://github.com/drwasho/openbazaar-go/tree/posts

[drwasho]

@drwasho

Thinking of refactoring this a bit @morebrownies by replacing reference: {peerId, listings [] } with just a general purposes tags []. That way users can use hashtags, or some symbol to denote a user, or put the slug/hash for a listings in there.

[drwasho]

@drwasho

Also I need to fix up the protobuf anyway.

[drwasho]

@morebrownies

Thinking of refactoring this a bit @morebrownies by replacing reference: {peerId, listings [] } with just a general purposes tags []. That way users can use hashtags, or some symbol to denote a user, or put the slug/hash for a listings in there.

hmm do we even need the general purpose tags array? From a UX perspective, it would be easier to enter #hashTags or @Handles directly into the title or longForm field(s). I'm thinking it would function a lot like Twitter.

3rd parties could also scrape the content within the title or longForm and index based on values found.

Maybe I'm over simplifying?

[drwasho]

@morebrownies

I read through the OBIP for the second time now and I love this OBIP so much. I see it leading to 2 great outcomes for OpenBazaar:

1. It will become easier to share / discover content within the ecosystem of OpenBazaar applications. Having the ability to communicate in app will increase the utility value of OpenBazaar while also increasing overall time spent in app. Shoppers / casual users may use OpenBazaar purely for communication needs and Vendors will have another avenue to engage with their followers. Having more user generated content within the platform is key to the growth of OpenBazaar.
2. OpenBazaar the protocol will also become more attractive to developers. They'll have the ability to build p2p social applications with payments + commerce layered in. This new ability for devs may lead to OpenBazaar powered photo apps spinning up on iOS or Android.

Looks good overall. I'm sure others can validate the schema a bit closer, but seemed on point to me.

Washington reacted with a heart emoji

[drwasho]

@drwasho

Thanks @morebrownies for the comments!

To your earlier points:

hmm do we even need the general purpose tags array? From a UX perspective, it would be easier to enter #hashTags or @Handles directly into the title or longForm field(s). I'm thinking it would function a lot like Twitter.

I kinda feel that tags sort just happened to Twitter and Instagram, and they integrated it as seamlessly as they could (battling with the idea of whether or not hashtags should count to the tweet length). If they were to design it from scratch, perhaps they would have had a dedicated space for tags?

But more concretely my reason for adding a dedicated tags section is two-fold:

1. I'm sparing a thought for client developers so they don't have to parse titles search for URLs, peerIds, handles, or listings hashes/slugs
2. Makes it easier for curators and influencers to clearly anchor their content to a store or collection of listings
3. tags allows users to embed other forms of metadata (i.e. location) without eating into space for content.

[drwasho]

@drwasho

Btw this is what the schema for a post looks like with tags:

{
    "post": {
        "slug": "test3",
        "vendorID": {
            "peerID": "QmVdst57mJuW8Tr9owADqWmirY5Gao9zZMnbbL4WavKJvB",
            "handle": "",
            "pubkeys": {
                "identity": "CAESIEokc1r9Wfe4IyqA9P/56dO+5W1Hv9eOi2PXdUBDUf5X",
                "bitcoin": "AjjghznFUNeAkgmEdKYOESzj+PXFvVHUv+jbNWWQKkwG"
            },
            "bitcoinSig": "MEQCIAaKg1Cr676NVo7dz1KibSvvhjyrAXQceYakKwYR13+oAiBmAWqIyTWMuMPeVItwPzS1N2SDYeR5H4cD+uxGv1AghQ=="
        },
        "title": "test3",
        "longForm": "This is a test post dawg.",
        "images": [
            {
                "filename": "cat",
                "original": "zb2rhe2o6WbHqcER5VUKsMUbQrmpCC6ihg8qZ4JS9wVgKz9wm",
                "large": "zb2rhmBUB9i7UkfmeD3obJYK3FFS5K8N8QHaUanG8UWLVBHiY",
                "medium": "zb2rhaFhqziCWk1zo5tMRxQEUchfvJFaGG4DY1anEoR4GnYrN",
                "small": "zb2rhbDCeEiTTunugWPaRRKFCfNKUaB7aCR53nrPnMa9usZXY",
                "tiny": "zb2rhgqJDbshwAgPjs7X2h4mDm3V3BpLbp4tFGqkg1LNkg9yV"
            }
        ],
        "tags": [
            "Yo"
        ],
        "timestamp": "2017-10-03T03:17:27.125836681Z"
    },
    "hash": "zb2rhiGehVLbtM6gpDbZ8f6R3r8xsw6hdidpiwZEuYskmnig5",
    "signature": "kX6Cc/8RzUWL7qSpwm8I1ytDGwQQjLshzY571Ejjo3lRZvfY4rOW5ZESLs33Gc330lFGprgRrEBA/ewoPdvFBQ=="
}

[drwasho]

@morebrownies

I kinda feel that tags sort just happened to Twitter and Instagram, and they integrated it as seamlessly as they could (battling with the idea of whether or not hashtags should count to the tweet length). If they were to design it from scratch, perhaps they would have had a dedicated space for tags?

No mainstream social tools I can think of utilizes an independent tag input. It seems like tagging is almost always accomplished within the body of text.

Using github as an example, you can type # and a overlay displays allowing you to quickly tag another thread.

Slack utilizes the same UX for tagging channels and users within text as well.

Same goes for Instagram and Twitter (which you mentioned above)

In my opinion, this allows for a much more fluid UX and allows users to write more natural without being required to bounce between multiple inputs. It has also become a well known pattern that people expect within applications.

[drwasho]

@morebrownies

But more concretely my reason for adding a dedicated tags section is two-fold:

1. I'm sparing a thought for client developers so they don't have to parse titles search for URLs, peerIds, handles, or listings hashes/slugs

It looks like Twitter does the parsing on their side to make it easier on developers. Something we could consider on the server side too: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-show-id

2. Makes it easier for curators and influencers to clearly anchor their content to a store or collection of listings

Not entirely sure how it makes it easier? I would think the opposite approach would easier on users.

3. tags allows users to embed other forms of metadata (i.e. location) without eating into space for content.

True, but you're suggesting a longer text input that would support 50,000 char. Is this really a concern? If users are way over the maximum limit of the short text, they could switch to longer text mode. Maybe UIs could adapt automatically to longer text mode without user action required. Have some ideas for this.

[drwasho]

@morebrownies

I just took a look at Medium and they do appear to support a independent tag input. This somewhat contradicts my comments above.

I think i'm in agreement now that the API should include some type of tags param. If anything, similar to what Twitter does, the server can auto-populate the value.

If certain clients want to expose a tag input, the server doesn't need to auto-populate in those scenarios. Maybe keeping it flexible is best.

Would love to hear opinions from others as well.

[drwasho]

Updates to the specification and reference implementation have been made: https://github.com/OpenBazaar/obips/pull/16/files

[drwasho]

Summary of the updates:

1. Added tags (replacing 'reference')
2. Instead of showing 1 thumbnail image for GETPosts, I show all of them in an array. Clients can control how many they choose to show.
3. Updated the protobuf and reference implementation code
4. Expanded the backwards compatibility section a little to make it clear that the impact of adopting posts will be minimally disruptive

[rmisio]

All posts need to be digitally signed to establish authenticity, and will include a slug for IPNS resolution so the publisher can edit their post.

This might just be semantics, but it would be better for the Post to have an ID (a unique non-maleable identifier). Otherwise we might find ourselves in the pickle we are in now with listings where we are using a slug as an ID, and the slug is public facing and if we ever want to give the user the ability to change the slug, it will create a lot of problems since multiple clients (desktop and search) are using it as an ID and not expecting that it could change.

I know there were some IPFS related complications to having both a slug and id. @tyler was brainstorming some potential solutions.

[rmisio]

Deletes an existing post: /ob/posts/:slug_or_hash

I don't think we should be able to delete by hash. A hash is just a version of a post. Does that mean you just want to delete the version or deleting any version of a post would delete the entire post (all versions). It's kind of confusing and ambiguius. I would just delete by id (well, slug if we are forced to use that as the id).

[rmisio]

google.protobuf.Timestamp timestamp = 7;

I see other parts of the app (e.g. notifications) also use the name "timestamp". I would think "createdAt" would be better. You may at some point want to add in a "updatedAt" making "timestamp" ambiguous.