Questions & Notes about the documentation

API
1

I’m not sure if these are replicated in the postman collections, I’m guessing there is a single source of truth (hopefully?) so yes.

  • Email: The example requests are all for setting multiple forwarding addresses, while it’s clear how to set 1 address since it’s just a comma separated list, when clearing the forwards, is it the same but with a blank list?
  • PURLs: The description for Retrieve a specific PURL says Retrieve a list of PURLs associated with an address
  • Status:
    • Create: Is external_url optional? I remember seeing something about social.lol cross-posting being related to this field. Along that vein, the flag to enable/disable an individual cross-post isn’t documented?
    • Update: Does this have the external_url field? I assume it can’t propegate to social.lol, but if you used it for eg a mailto, then can it be updated?
    • Statuslog / Statuslog Latest: Is there a difference between the /statuslog and /statuslog/latest endpoints, my guess is the latter is the most recent 50 or some paginated value? The former seems dangerous if uncapped and redundant if capped?
  • Web:
    • Update: What is the difference between publishing and just updating?
    • Upload PFP: The description seems wrong? Also, the request example doesn’t include how you’d send the image via curl, not something super necessary but just for completeness, since each method of making a request has their own way of sending a file.

Hopefully none of this came across as critical, I love the documentation. Plus it was way easier to understand than trying to convert the postman collection to a specific language, their builder is per method, not the collection as a whole.

1 Like
2

The API documentation needs some care (been on my list of things to do for a while), so I’m sorry for the inconsistencies and ambiguity!

Email: Yep, sending an empty value should clear the stored forward addresses (and disable forwarding).

PURLs: Fixed this!

Status: Yes, external_url is totally optional. Everything you can do with Create you can also do with Update, so that includes external_url and skip_mastodon_post (which isn’t named very well at this point, but that will likely be cleaned up in a future API version). /statuslog/latest is capped (though I need to add pagination), whereas /statuslog isn’t. So, yeah, redundant and dangerous indeed! Will fix soon.

Web: Updating stores your changes in a draft form, while Publishing makes those changes public. Fixed the description on the PFP endpoint. And yeah, the script I have that parses Postman collection data doesn’t do a great job of the CURL stuff for anything involving files/images—but I’ll sort this out in the upcoming documentation rewrite!

Thanks for the attention to the detail and pointing out these issues!

3

Ah okay, so the source of truth in this case is this folder on the repo?

I wonder if you have a set up Public Postman collection, it might be cool to fork and make improvements directly as a PR in Postman :smiley: or on the GitHub if that seems unnecessary.

1 Like
4

I haven’t played with the public collection stuff before, but I’ll give it a spin soon to see if that’s the way to go!