OwnYourSwarm Documentation

To begin using OwnYourSwarm, you will need a server that supports Micropub. Micropub is the API standard that OwnYourSwarm uses to send checkins to your website.

After you sign in with your domain and authorize OwnYourSwarm to create posts on your website, you will then connect your Swarm account. At that point, your account is active, and any future checkins will be sent to your website as soon as you check in on Swarm.

🔗 Authentication

The first step to using OwnYourSwarm is to authorize it to post to your website. To do this, you will need to support the IndieAuth spec. When you first attempt to sign in, you will be walked through the process of setting up the required pieces.

To quickly get started, you can use the indieauth.com service to handle your authorization endpoint and token endpoint. Your Micropub server will need to be able to verify the tokens itself. Copy the lines below to your home page to use the indieauth.com services to bootstrap your implementation.

<link rel="authorization_endpoint" href="https://indieauth.com/auth">
<link rel="token_endpoint" href="https://tokens.indieauth.com/token">

You can read more about implementing these two components yourself on the IndieWeb wiki.

Once OwnYourSwarm has obtained an access token, it will send it along with each request in an HTTP Authorization header like the below.

HTTP/1.1 POST /micropub
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxx

🔗 Checkins

The request your Micropub endpoint receives will always be a JSON payload containing a Microformats 2 object describing the checkin.

The basic structure of a JSON payload looks like the below.

{
  "type": [
    "h-entry"
  ],
  "properties": {
    "published": [
      "2017-03-24T17:30:32-07:00"
    ]
    ...
  }
}

The properties in the h-entry will depend on the checkin. The set of properties possible is listed below. Note that in the Micropub JSON syntax, all properties will be arrays, even if there is only one value, e.g. the "published" date above.

You can see an example of a full object after you connect OwnYourSwarm and check in somewhere, then look at your dashboard.

published

The published property will contain the ISO8601 timestamp of the date of the checkin. This timestamp will include the timezone offset of the checkin.

syndication

The syndication property will contain the Swarm permalink to the checkin. Note that the Swarm permalinks sent in this parameter are not publicly visible, they only visible to your Swarm friends.

photo

If your checkin includes one or more photos, then the URL to your photos will be in the photo property.

Note that photos are sent from the Swarm app asynchronously, so it's actually possible for your checkin to be created before the photo has been uploaded to the server, such as when you're on a slow network connection. If this happens, the checkin posted to your website will not include a photo initially. See the Updates section below for a description of how to handle receiving the photo after the initial checkin has been created.

content

If your checkin contains a note, or if you've tagged people in the checkin, then the content property will be included. The content property will be either a plain string, or an object containing both a plaintext and HTML version of the text, depending on whether there is any HTML formatting in the text.

If you tag people in the checkin, their names will be hyperlinked to their Foursquare profile URLs. (If they also use OwnYourSwarm, then their personal URL will be used instead.)

Note that when you tag people in a checkin, Swarm adds the text "with X, Y, Z" to the end of the text automatically.

Content with HTML
  "content": [{
    "value": "#indiewebcamp day 1 - with Aaron",
    "html": "#indiewebcamp day 1 - with <a href="https://aaronparecki.com/">Aaron</a>"
  }]
Plaintext Content
  "content": ["Checkin shout"]

category

The category property will contain any hashtags you've used in your checkin text, as well as an h-card for any people you've tagged in the checkin.

Hashtags in the text will be included as a string without the leading "#", e.g.

  "content":[
    "#indiewebcamp day 1"
  ],
  "category": [
    "indiewebcamp"
  ]

If you tag one or more people in the checkin, then their information will be included as a person tag like the below.

  "content": [{
    "value": "#indiewebcamp day 1 - with Aaron",
    "html": "#indiewebcamp day 1 - with <a href="https://aaronparecki.com/">Aaron</a>"
  }],
  "category": [
    "indiewebcamp",
    {
      "type": ["h-card"],
      "properties": {
        "name": ["Aaron"],
        "url": ["https://foursquare.com/user/59164", "https://aaronparecki.com/"],
        "photo": ["https://igx.4sqi.net/img/user/300x300/QREPPTELDVOJ5CE5.jpg"]
      }
    }
  ]

checkin

The information about the venue you've checked in to will be included in the checkin property. The value of this property will be an h-card with the following properties.

Always present:
  • name - The name of the venue. This will always be an array with a single value.
  • url - The URL(s) for the venue. The first value will always be the Foursquare URL of the venue. If the venue has a website, then the website will be included as another value. If the venue has a Twitter account, the Twitter profile URL will also be included.
Present when available from Swarm:
  • latitude - The latitude of the venue. This may be intentionally less accurate for private venues.
  • longitude - The longitude of the venue. This may be intentionally less accurate for private venues.
  • street-address - The street address of the venue
  • locality - The city or other large geographical region, e.g. "Portland"
  • region - The state or region, e.g. "Oregon"
  • country-name - The country name, e.g. "United States"
  • postal-code - The postal code, e.g. "97214"
  • tel - The venue's phone number

Read more about the Micropub JSON syntax.

🔗 Updates

When you add a photo to a checkin on Swarm, occasionally it will be uploaded asynchronously after the checkin itself is created. This means the initial checkin sent to your site will sometimes not include a photo.

When this happens, OwnYourSwarm will periodically poll your recent checkins until a photo appears, then send a Micropub update request to add it to your post. The polling is based on an exponential back-off schedule. Below is an example request to add a photo.

{
  "action": "update",
  "url": "https://example.com/your/checkin/url",
  "add": {
    "photo": [
      "https://igx.4sqi.net/img/general/original/59164_nCV1s2M0arGbdr_Tdx6sAhWD_BKPbyuMx6o-SXvIKWM.jpg"
    ]
  }
}

There may be one or more URLs in the photo property. Once a photo is found, OwnYourSwarm will stop polling the checkin.

🔗 Coins

The coins that Swarm awards to checkins are sent to your checkins via Webmention. Each description of the coins awarded is given a URL on OwnYourSwarm, and a Webmention is sent from that URL to your checkin URL. OwnYourSwarm waits about 5 seconds after posting your checkin via Micropub before it sends these Webmentions.

If your website is already set up to receive comments via Webmention, then you should start seeing these as normal comments automatically. These URLs are marked up with h-entry, including a in-reply-to property linking to your original checkin.

The coin pages also have a vendor-specific property in the h-entry, p-swarm-coins, indicating the number of coins Swarm awarded for this item. The only thing you need to worry about beyond handling this as a normal Webmention comment is parsing the p-swarm-coins property if you want to show that.

A complete example of this comment is given below in parsed Microformats 2 JSON format.

{
  "type": [
    "h-entry"
  ],
  "properties": {
    "author": [
      {
        "type": [
          "h-card"
        ],
        "properties": {
          "photo": [
            "https://ss1.4sqi.net/img/points/coin_icon_crown.png"
          ],
          "url": [
            "https://swarmapp.com/"
          ],
          "name": [
            "Swarm"
          ]
        },
        "value": "https://swarmapp.com/"
      }
    ],
    "name": [
      "You're still the Mayor. Time to make some rules!"
    ],
    "swarm-coins": [
      "3"
    ],
    "in-reply-to": [
      "https://aaronparecki.com/2017/03/24/7/"
    ],
    "url": [
      "https://ownyourswarm.p3k.io/checkin/58d57db03bd4ab039c76dfed/144ba522fe8454c1e97aef5735329f55"
    ],
    "published": [
      "2017-03-24T13:12:42-07:00"
    ],
    "content": [
      {
        "html": "You're still the Mayor. Time to make some rules!",
        "value": "You're still the Mayor. Time to make some rules!"
      }
    ]
  }
}

The author of the h-entry will always be Swarm, but the profile photo will change depending on the icon Swarm uses for each line.

Read more about coins sent as Webmentions.

🔗 Likes and Comments

When people like and comment on your checkin, OwnYourSwarm will backfeed these responses to your post via Webmention. OwnYourSwarm creates a URL for each like and comment, and sends a Webmention from that URL to your checkin it created.

These pages are marked up as a traditional like and comment using h-entry with the appropriate like-of or in-reply-to property. If your website is set up to handle likes and comments already, then these will work without any additional work. If you haven't yet set up the ability to receive likes and comments, then once you can handle these, you will also be able to receive likes and comments from thousands of other IndieWeb sites!

See Webmention developers for details on how to accept and verify webmentions on your website.

OwnYourSwarm will poll your last 100 checkins looking for new likes and comments on your checkins. Whenever you check in, your polling interval is reset to the highest level. Your account will be checked frequently at first, slowly tapering off if there is no new activity. This should keep a balance between catching recent activity on your checkins while not overloading the system.