winks/pants_spec.md Secret

## pants_spec.md

      
    Raw
  

              pants_spec.md
            
          
    pants is a pantastic (micro)publishing platform.

There are several key assumptions:

As a pants user you MUST have a globally unique identity, this is
defined as a domain you control, i.e. if your account is available at
"pants.example.org", then that is your identity/username,
which MUST NOT be changed
your display name MAY deviate from that, but it is informal and can
be changed arbitrarily
each post MUST have a unique (per identity) identifier and thus, url. It
MUST be in the form  "[IDENTITY]/[IDENTIFIER]", i.e.
"pants.example.org/example123"
A list of posts SHOULD be available

at "[IDENTITY]/posts" in html form: all posts
at "[IDENTITY]/posts.json" in JSON Format X1.2: all posts
at "[IDENTITY]/posts.json?updated_since=[UNIXTIMESTAMP]" in JSON Format X1.2:
all posts not older than [UNIXTIMESTAMP]


Each post MUST return json data in (Format X1.1) under the url
"[IDENTITY]/[IDENTIFIER].json", i.e. "pants.example.org/example123.json"
info about your identity MUST be available at:

"[IDENTITY]/user" (free form) and
"[IDENTITY]/user.json" (Format X2)


There SHOULD be a profile picture/avatar available at "[IDENTITY]/user.jpg", i.e.
"pants.example.org/user.jpg"
You can add other identities as friends, this is not specified further
than the need to have their identity.
When you create a new post, pants SHOULD send a ping to
"[otheridentity]/ping" as HTTP POST in Format X3

Format X1.1

{
  "guid":"pants.example.org/example123",
  "url":"http://pants.example.org/example123",
  "published_at":"2014-06-28T13:53:48.373+02:00",
  "edited_at":"2014-06-28T13:53:48.372+02:00",
  "body":"#pants - asdf",
  "body_html":"\u003cp\u003e\u003ca href=\"/tag/pants\" class=\"hashtag\"\u003e#pants\u003c/a\u003e - asdf\u003c/p\u003e\n",
  "domain":"pants.example.org",
  "slug":"example123",
    "sha":"0000000000000000000000000000000000000000",
  "previous_shas":[],
  "tags":["pants"]
}
Format X1.2

[
{
  "guid":"pants.example.org/example123",
  "url":"http://pants.example.org/example123",
  "published_at":"2014-06-28T13:53:48.373+02:00",
  "edited_at":"2014-06-28T13:53:48.372+02:00",
  "body":"#pants - asdf",
  "body_html":"\u003cp\u003e\u003ca href=\"/tag/pants\" class=\"hashtag\"\u003e#pants\u003c/a\u003e - asdf\u003c/p\u003e\n",
  "domain":"pants.example.org",
  "slug":"example123",
    "sha":"0000000000000000000000000000000000000000",
  "previous_shas":[],
  "tags":["pants"]
},
{...}
]
Format X2

{
  "display_name":"USERNAME",
  "domain":"pants.example.org",
  "locale":"en",
  "url":"http://pants.example.org/"
}
Format X3

POST /ping HTTP/1.1
Host: pants2.example.org
Content-Length: 39

url=http://pants.example.org/example123

Appendix 1, the canonical implementation


The user MAY login at "[IDENTITY]/login"
Posts including a certain tag (as defined by "#[SOMETHING]" in the body)
SHOULD be available at "[IDENTITY]/tag/[SOMETHING]".
Posts published on a certain day SHOULD be available at
"[IDENTITY]/[YYYY-MM-DD]".