Case study in APIs

The issue contains API request and response examples but names no repository file, test, or entry point to change. Start by locating the code that handles the shown post-creation response; done would require a maintainer-defined higher-level result that exposes the created post location and addresses the broader API concerns.

This is the info that my app sends to a server that then converts it to Bluesky's internal language as the arguments for a call that will create a new post. These are standard names for these things that any experience programmer would immediately recognize. Users would recognize them too, except perhaps urlsite.

{
    "title": "",
    "description": "Room for One More on Mount Rushmore?",
    "mailaddress": "",
    "password": "",
    "urlsite": "https://bsky.social/",
    "link": "https://politicalwire.com/2025/06/29/room-for-one-more-on-mount-rushmore/"
    }

And this is what comes back.

{
    "uri": "at://did:plc:zxb2lwpxo4axkkkgjwqand24/app.bsky.feed.post/3lsqtoowg2h2h",
    "cid": "bafyreifhet2772xmic24qr4xbui4l5lllvgek2a7kmmchojwwkufvzalci",
    "commit": {
        "cid": "bafyreicjjsd4ixlezubezaxzfaqxxpwlvoxdqwyxblnme5uh6ehklxth3a",
        "rev": "3lsqtoowpsx2h"
        },
    "validationStatus": "valid"
    }

Some of the terms mean something, like URI and commit, but their values don't mean anything to me, don't shed any light on what the result was except "validationStatus": "valid" seems to say "it worked." :-)

And nowhere in this package is the one piece of info every freaking app would need after posting something -- where the F did you put it!??

I don't have a problem with detailed internal info coming back from a query. I know APIs are used for lots of applications. But this is a problem I've seen repeatedly in their API, they push the work out to the developer where they for sure have the code internally to do it, and could factor out the work, instead of making us all implement what we're sure to need, do it once and provide a higher level interface.

Just some feedback for the Bluesky folk, and a caution when designing your own APIs, write some code that runs against your API, you'd see these problems right away.