Questions & Notes about the documentation

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 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, 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

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!

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

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!