APEX: Integration Playground - Bluesky

In what can be considered the Part I of this Integration Playground Series I ranted about Reading Posts from Hashnode. The end goal was to be able to re-post the existing content to other platforms, specifically Bluesky.

In essence it is as simple as any other REST API integration, so I keep this one short and focus on the parts I found the most interesting on my journey.

About this Post

I have joined the some members of the Oracle APEX/DB development team members on Bluesky, Sydney Nurse → @synuora.bsky.social. In order to automate re-posting from Hashnode, I worked on an APEX app that will allow me to review my post collections and allow me to re-post at the click of a button to Bluesky or perhaps further down the road other services.

Bluesky’s SDK is based on Typescript and Python but Restfully is standard JSON. Basic posting is simple with linking and styling to most interesting part of the API usage. There are other areas such as labelling or embedding but me as a Bluesky newbie, I’ll stick to posts and links for now.

Bluesky APIs

The Bluesky application is built on atproto, unlike some social media platforms, there is not one centralized API. It is more like the classic web, there can be multiple independent service providers and account hosts.

The api host and various endpoints will vary depending on the type of interactions. This is describe in the API Hosts and Auth section of the documentation.

The API or SDK docs target TypeScript and Python languages with basic examples using CURL which is okay but not my preferred way to discovery an APIs required, optional parameters and body structure.

The entries that interested me are:

• Create Session - Create an authentication session

• Create Record - Create a single new repository record & requires authentication

Create session

OAuth is the primary mechanism in authenticated transfer protocol (atproto) for clients to make authorized requests to Personal Data Server (PDS) instances. A PDS stores the user data repository and optionall the user’s handle.

When reviewing the create session documentation, we see that it is a POST operation, its uri and the request / response structure.

The Get Started section provides an example on its usage for Typescript, CURL, & Python.

curl -X POST $PDSHOST/xrpc/com.atproto.server.createSession \
    -H "Content-Type: application/json" \
    -d '{"identifier": "'"$BLUESKY_HANDLE"'", "password": "'"$BLUESKY_PASSWORD"'"}'

The example show the POST call, content type and body but references a $PDSHOST. After a long search of the documentation I came upon this in the OAuth Client Implementation under Components and Authorization Request

• Pushed Authentication Requests (PAR) are required for all client types.

• The client next makes a Pushed Authorization Request via HTTP POST request to the pushed_authorization_request_endpoint.

• The user will authenticate with the server and approve the authorization request, using the "authorization interface" on the PDS/entryway.

Bluesky runs many PDSs. Each PDS runs as a completely separate service in the network with its own identity. A user should not be expected to understand or remember the specific host that their account is on.

To enable this, Bluesky introduced a PDS Entryway service. This service is used to orchestrate account management across Bluesky PDSs and to provide an interface for interacting with bsky.social accounts.

So, with these details and the table of API Hosts and Auth, we can select the Entryway host from the Bluesky Services.

This service is similar to the Adobe PDF Services which accepts credentials in the Request Body. The user identifier and password. The session returns user details and the JWT access token that is used in subsequent API invocations.

declare
    l_client_id             VARCHAR2(1000)  := '__BLUESKY_HANDLE__';
    l_client_secret         VARCHAR2(1000)  := '__PASSWORD__';
    l_response_clob         CLOB;
    l_token_url             VARCHAR2(1000)  := 'https://bsky.social/xrpc/com.atproto.server.createSession';
    l_body                  JSON_OBJECT_T   := new JSON_OBJECT_T;
    l_jwt_token             VARCHAR2(1000);
begin

    -- BlueSky Services
    -- Setup up initial parameters

    l_body.put('identifier',l_client_id);
    l_body.put('password',l_client_secret);

    -- Get Token
    apex_web_service.g_request_headers.delete();
    apex_web_service.g_request_headers(1).name  := 'Content-Type';
    apex_web_service.g_request_headers(1).value := 'application/json';

    l_response_clob := apex_web_service.make_rest_request(
        p_url           => l_token_url,
        p_http_method   => 'POST',
        p_body          => l_body.to_string
        );

    l_jwt_token := JSON_VALUE(l_rest_token,'$.accessJwt');

    DBMS_OUTPUT.PUT_LINE(l_jwt_token);

END;

Create Record

Similarly the Get Started section provides an example on creating a post or record. The create record API request is a standard JSON structure of a specific collection or Lexicon record type. Outside of the examples, it was fairly difficult to find a clear & user friendly description or the various record types.

The Lexicon are in the Bleusky GitHub repository => atproto / lexicons with post under the app/bsky/feed/post.json. The id signifies the record type and under the record attribute, we see the required and optional attributes and each type and description.

{
  "lexicon": 1,
  "id": "app.bsky.feed.post",
  "defs": {
    "main": {
      "type": "record",
      "description": "Record containing a Bluesky post.",
      "key": "tid",
      "record": {
        "type": "object",
        "required": ["text", "createdAt"],
        "properties": {
          "text": {
            "type": "string",
            "maxLength": 3000,
            "maxGraphemes": 300,
            "description": "The primary post content. May be an empty string, if there are embeds."
          },,
          "facets": {
            "type": "array",
            "description": "Annotations of text (mentions, URLs, hashtags, etc)",
            "items": { "type": "ref", "ref": "app.bsky.richtext.facet" }
          },
          "createdAt": {
            "type": "string",
            "format": "datetime",
            "description": "Client-declared timestamp when this post was originally created."
          }
        }
      }
   }
}

Basic Post

The collection, text and createdAt attributes is enough for a basic post but this makes for a boring post, so we’ll expand the record, adding a rich text facet with at least a url link back to the original hashnode post.

Links, Mentions, & Rich Text

Bluesky does not use a markup language, instead, it uses a concept of rich text facets which point at locations in the text.

Facets are used to enrich the post record, adding links, mentions and rich text.

{
  "lexicon": 1,
  "id": "app.bsky.richtext.facet",
  "defs": {
    "main": {
      "type": "object",
      "description": "Annotation of a sub-string within rich text.",
      "required": ["index", "features"],
      "properties": {
        "index": { "type": "ref", "ref": "#byteSlice" },
        "features": {
          "type": "array",
          "items": { "type": "union", "refs": ["#mention", "#link", "#tag"] }
        }
      }
    },
    "mention": {
      "type": "object",
      "description": "Facet feature for mention of another account. The text is usually a handle, including a '@' prefix, but the facet reference is a DID.",
      "required": ["did"],
      "properties": {
        "did": { "type": "string", "format": "did" }
      }
    },
    "link": {
      "type": "object",
      "description": "Facet feature for a URL. The text URL may have been simplified or truncated, but the facet reference should be a complete URL.",
      "required": ["uri"],
      "properties": {
        "uri": { "type": "string", "format": "uri" }
      }
    },
    "tag": {
      "type": "object",
      "description": "Facet feature for a hashtag. The text usually includes a '#' prefix, but the facet reference should not (except in the case of 'double hash tags').",
      "required": ["tag"],
      "properties": {
        "tag": { "type": "string", "maxLength": 640, "maxGraphemes": 64 }
      }
    },
    "byteSlice": {
      "type": "object",
      "description": "Specifies the sub-string range a facet feature applies to. Start index is inclusive, end index is exclusive. Indices are zero-indexed, counting bytes of the UTF-8 encoded text. NOTE: some languages, like Javascript, use UTF-16 or Unicode codepoints for string slice indexing; in these languages, convert to byte arrays before working with facets.",
      "required": ["byteStart", "byteEnd"],
      "properties": {
        "byteStart": { "type": "integer", "minimum": 0 },
        "byteEnd": { "type": "integer", "minimum": 0 }
      }
    }
  }
}

Posting to Bluesky

If you’ve followed the previous post, APEX: Integration Playground - Hashnode, you will have a response body that you can work with. I’ve stored my responses in a JSON column in my DB.

Let’s get the values we need

BEGIN
    select 
        j3.title, j3.url,j3.publishedAt, replace(replace(substr(j3.brief,0,200),CHR(10),'\n'),CHR(13),'\n') brief
    into :P2_TITLE,:P2_URI, :P2_PUBLISHED_DATE, :P2_BRIEF
    from "BLOGS_PUBLICATIONS" ,json_table
        (
        "POSTS",'$.data' 
        columns(
            nested path '$.publication.posts.edges[*]' 
            columns (
                id          varchar2(4000)  path '$.node.id',
                title       varchar2(4000)  path '$.node.title',
                url         varchar2(4000)  path '$.node.url',
                publishedAt varchar2(4000)  path '$.node.publishedAt',
                brief       varchar2(4000)  path '$.node.brief'
            )
        )
        )j3
    where j3.id = :P2_ID;

    APEX_DEBUG.INFO('Current values for the post :%S published at:%S at this URI: %s', :P2_TITLE, :P2_PUBLISHED_DATE, :P2_URI);

END;

When this page is navigated to, I set the ID that I need and use a pre-rendering Before Regions Process to setup the rest of the page items.

The next step is to use the session JWT token while performing the Post of the Post.

declare
    l_response_clob         CLOB;
    l_rest_token            VARCHAR2(1000); -- retrieved earlier
    l_rest_url              VARCHAR2(1000)  := 'https://bsky.social/xrpc/com.atproto.repo.createRecord';
    l_post                  JSON_OBJECT_T   := new JSON_OBJECT_T; -- Post to be posted
    l_body                  JSON_OBJECT_T   := new JSON_OBJECT_T; -- Request Body
begin

    -- Build up my Post with the Hashnode content stored in my page items
    -- !! I've added extra lines here for readability but have used a single line in my code !!

    -- The required text with any line breaks
    l_post := JSON_OBJECT_T.parse('{"text":"' || :P2_TITLE || '\n\n' 
       || :P2_BRIEF || '...\n\nShared from an APEX application."}');

    -- The required createdAt date
    l_post.put('createdAt', :P2_PUBLISHED_DATE); 

    -- Add the facet to link to my Hashnode blog post 
    l_post.put ('facets', JSON_ARRAY_T.PARSE('[{"index":{"byteStart": 0,"byteEnd": '  -- Start position for the feature
       || TO_CHAR(LENGTH(:P2_TITLE))                                                  -- End position for the feature
       || '},"features": [{"$type": "app.bsky.richtext.facet#link","uri": "'          -- Feature type (uri)
       || :P2_URI || '"}]}]'));                                                       -- URI
    -- !! Again, I have added extra lines but you may recieve errors by wrapping the code in this manner!!

    APEX_DEBUG.INFO('Post Text %s',l_post.to_string);

    -- Add the all required fields to the request Body including the Post Record
    l_body := NEW JSON_OBJECT_T;
    l_body.put('repo','synuora.bsky.social');      -- User Bluesky Handle
    l_body.put('collection','app.bsky.feed.post'); -- Type of Record
    l_body.put('record', l_post);                  -- The Record to be posted


    APEX_DEBUG.INFO('Posting %s',l_body.to_string);

    -- Set additional API parameters
    apex_web_service.g_request_headers.delete();
    apex_web_service.g_request_headers(1).name  := 'Authorization';
    apex_web_service.g_request_headers(1).value := 'Bearer ' || l_rest_token;
    apex_web_service.g_request_headers(2).name  := 'content-type';
    apex_web_service.g_request_headers(2).value := 'application/json';

    -- Make the call
    l_response_clob := apex_web_service.make_rest_request(
        p_url                       => l_rest_url,
        p_http_method               => 'POST',
        p_body                      => l_body.to_string
    );

    APEX_DEBUG.INFO('Post Response: %s',l_response_clob);

END;

If all goes well

Conclusion

The more I use APIs, I can attest that not all APIs and in particular API documentation are equal. I found the structure and descriptions on the Bluesky APIs not as simple as the Adobe PDF Services or even various Oracle API docs.

In the end I was successful; using a blend of API doc, example tutorials, GitHub info, and trail & error, to create a record.

This was a simple example and I’m sure much richer posts could be created, with wrapper functions to support the JSON document construction of the record but this was enough for me.

Things to note, that Posts or Records have a maximum length and I’ve limited the main portion of the brief to 200 characters, ensuring that I would not hit the 3000 limit on the strings. I found this gave a uniform look to the post shared in this manner.

Next time a GenAI summary fitting within the limit would be nice.

At any rate, I hope you found this interesting and hopefully useful.