DEV Community: Torin Rozzelle

Part 2: Describing the API

Torin Rozzelle — Sun, 07 May 2023 15:44:26 +0000

In the first article in this series, we started writing our ChatGPT plugin by building an HTTP proxy in express that authenticates with Bluesky and proxies requests to Bluesky's endpoints.

In this article, we're going to build the metadata files that tell ChatGPT about the API and what structure it can expect the data in the requests and responses to take. After that, we'll register the plugin to run locally and make our first successful request in the chat.

First, let's create the plugin manifest by creating the directory .well-known and, in it, a file called ai-plugin.json. If you haven't encountered the .well-known folder before, it's a relatively recent IETF standard that defines a standardized folder that contains metadata about what services are available on that server.

The ai-plugin.json should look like this:

{  
  "schema_version": "v1",  
  "name_for_human": "Bluesky (no auth)",  
  "name_for_model": "bluesky",  
  "description_for_human": "Plugin for accessing Bluesky, you can search for profiles and posts.",  
  "description_for_model": "Plugin for accessing Bluesky, you can search for profiles and posts.",  
  "auth": {  
    "type": "none"  
  },  
  "api": {  
    "type": "openapi",  
    "url": "http://localhost:3005/openapi.yaml",  
    "is_user_authenticated": false  
  },  
  "logo_url": "http://localhost:3005/logo.png",  
  "contact_email": "legal@example.com",  
  "legal_info_url": "http://example.com/legal"  
}

The fields are mostly self-explanatory but I want to call your attention to description_for_model and the api object.

description_for_model lets us write a description of the plugin that is provided to ChatGPT as part of the metadata it ingests to understand what’s going on. For lack of a better term, it’s a prompt. Where description_for_human has a max length of 120 chars, description_for_model has a max length of 8,000 chars. We don’t need to touch it yet but in the future you’ll see how we can use it to provide important contextual data that guides ChatGPTs inferences.

The api object defines the API specification we’re using and tells ChatGPT where to find the OpenAPI spec file that actually tells it about our API. Since we’re handling authentication in our middleware, we can set auth: { type: none } and is_user_authenticated: false. Once Bluesky has more robust authentication in place and OpenAI permits user-level authentication, our plugin should be refactored to move authentication from the middleware to as close to ChatGPT as possible.

OpenAPI Specification

As of this writing, I don't believe a proper OpenAPI 3.0 spec of either the AT Protocol or Bluesky's API has been published. If we were implementing an API for another service that already had the API well-documented in the OpenAPI format, we would be able to slot it in, make a few minor tweaks, and be on our way. Because we don’t, we’re going to have to write one.

The two resources that are the most helpful here are the atproto lexicon docs and the shape of the data in the response that we get when we call each endpoint. We’re going to focus on app.bsky.actor.getProfile as our first endpoint.

Consulting the app.bsky.actor lexicon, we see that getProfile takes a single parameter:

{
  "lexicon": 1,
  "id": "app.bsky.actor.getProfile",
  "defs": {
    "main": {
      "type": "query",
      "parameters": {
        "type": "params",
        "required": [
          "actor"
        ],
        "properties": {
          "actor": {
            "type": "string",
            "format": "at-identifier"
          }
        }
      },
      "output": {
        "encoding": "application/json",
        "schema": {
          "type": "ref",
          "ref": "app.bsky.actor.defs#profileViewDetailed"
        }
      }
    }
  }
}

The actor parameter is expected to be in the format of an at-identifier, or, more commonly, a user handle. On Bluesky, these take the form of @torin.bsky.social or @bsky.app.

Let's start to write our openapi.yaml:

openapi: 3.0.1
info:
  title: Bluesky client
  description: Plugin for accessing Bluesky, you can search for profiles and posts.
  version: 'v1'
servers:
  - url: http://localhost:3005

We start with the metadata, which is self-explanatory.

Let’s add the app.bsky.actor.getProfile endpoint:

paths:
  /app.bsky.actor.getProfile:
    get:
      operationId: getProfile
      summary: Get user profile by handle
      description: Fetches a user's profile using the user's handle, which is usually in the form of a.b.c or a.b. Ex. torin.bsky.social
      parameters:
        - in: query
          name: actor
          schema:
            type: string
          description: The handle of the user profile to fetch.
          required: true

We will add each endpoint we want to define in the paths section. In /app.bsky.actor.getProfile, we first define the type of request (get). The operationId is the unique name for the operation (ChatGPT really needs this). Summary is a short, imperative statement of what the endpoint does.

description is more interesting. As we’ll see later on, the descriptions that we provide for each operation are ostensibly small mini-prompts that we can use to help ChatGPT infer what to do and how to do it. Here, I’ve added a little bit of help to describe the structure of Bluesky handles.

The parameters defines the input parameters for the request, in this case a single string called actor. The parameters for the GET requests are sent as query parameters, so we state in: query. The schema is the expected type of the parameters or, in the case of an object, the shape of the object and the types of the values within it.

So far, so good. Let’s make a call to this endpoint and see what gets returned.

curl 'localhost:3005/api/app.bsky.actor.getProfile?actor=bsky.app' | jq '.'

{
  "did": "did:plc:z72i7hdynmk6r22z27h6tvur",
  "handle": "bsky.app",
  "displayName": "Bluesky",
  "description": "Official bluesky account (check domain 👆)\n\nFollow for updates and announcements",
  "avatar": "https://cdn.bsky.social/imgproxy/LQdoaVquF7hEwCIJ1FW_AL52O95YYgoNyKzr9C-ibik/rs:fill:1000:1000:1:0/plain/bafkreic5kmqlhrhbfnh2bx6fsetvkra4noqja5ngsnnadrvubd6jcoc3ae@jpeg",
  "banner": "https://cdn.bsky.social/imgproxy/cFuBuKQpl9WM_Hq27hjMRm9OzlISj3BZmd4eU6o5JO0/rs:fill:3000:1000:1:0/plain/bafkreif7lzr3l7ysgwfuiv7q6rtlyebup2mizdgmbhmsunowspiq7m4oee@jpeg",
  "followsCount": 11,
  "followersCount": 12230,
  "postsCount": 22,
  "indexedAt": "2023-04-12T17:37:56.123Z",
  "viewer": {
    "muted": false,
    "blockedBy": false
  },
  "labels": []
}

We can now describe whatever data we want ChatGPT to be aware of in the response section of ai-plugin.yaml. Right now, we want to define everything that gets returned so that ChatGPT can make decisions on the data. Once we've fleshed out our spec a bit more, ChatGPT will be able to infer from our definitions to chain API calls to get what the user is asking for.

Something to be aware of is that we will, at some point, need to make some decisions on what data we are passing back and forth. The response for getProfile is light. Our response is ever only going to be 20-30 lines or 300-400 tokens. Once we start asking ChatGPT to search or pull down posts, the response quickly balloons to an unmanageable size.

Still under get, we define what responses we can expect to receive.

      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '400':
          description: Bad Request. Missing handle parameter.
        '500':
          description: Internal server error. API error or proxy error.

The encoding of the response is application/json. Under schema, we add a reference to a component schema that we will add to the next section. This helps to keep the YAML file uncluttered by grouping endpoints with endpoints and schemas with schemas.

The components section is where we define various reusable definitions. API responses will contain many of the same types of objects. Our call to app.bsky.actor.getProfile returns a single profile but if we make a call toapp.bsky.actor.getProfiles, we can expect to get an array of Profiles back. Much like a type definition or an interface in Typescript, we can describe composable definitions that keep our spec clean and maintainable.

components:
  schemas:
    Profile:
      type: object
      properties:
        did:
          type: string
          example: "did:plc:cnd3evrzk24itsn3la76mea5"
        handle:
          type: string
          example: "torin.bsky.social"
        displayName:
          type: string
          example: "juvenile human chicken"
        description:
          type: string
          example: "Second-order effect enthusiast → progressive campaigning → software engineer."
        avatar:
          type: string
          example: "https://cdn.bsky.social/imgproxy/XL3MtdWOesDtgxdJ9APH5YlXe-0Yoe6Tyh9SgcazlR0/rs:fill:1000:1000:1:0/plain/bafkreifas5cditu4pnt3yi5ory77goeqx7x4ie3ta4d4nps7mpu7bwniiu@jpeg"
        banner:
          type: string
          example: "https://cdn.bsky.social/imgproxy/gwstOMUjJRi-xmHvJtTr3e880kV1FABx1HTfJHhrw58/rs:fill:3000:1000:1:0/plain/bafkreibdwgx5wyivhupj2epaj3wsevpdsynvu6a64tg4kxx6kc3rlacaxu@jpeg"
        followsCount:
          type: integer
          example: 248
        followersCount:
          type: integer
          example: 229
        postsCount:
          type: integer
          example: 812
        indexedAt:
          type: string
          format: date-time
          example: "2023-04-12T16:40:18.256Z"
        viewer:
          type: object
          properties:
            muted:
              type: boolean
              example: false
            blockedBy:
              type: boolean
              example: false
            following:
              type: string
              example: "at://did:plc:e42n3y4awcoz262k6x6bxu75/app.bsky.graph.follow/3jt7hmgjigv2z"
        labels:
          type: array
          items:
            type: string

One by one, we describe each part of the response object and give it's type. We can also give an example of what it is expected to look like. I've overdone it in the example above, ChatGPT understands what a boolean is, but giving it examples of idiomatic data like the DID, which is atproto's identifier for individuals, or the URI for the social graph, which is in the form of atproto's URI scheme, is important. If you've used ChatGPT, you know that by giving it a few examples you can greatly increase the quality of its responses.

Making the First Call

This should be enough for ChatGPT to respond with the details of a user’s profile if we give it a handle.

Let’s register our plugin and try to run it.

In the ChatGPT interface, we’ll open a new thread and select Plugin as the model. Opening the Plugin Store, we select Develop your own plugin and we’ll get a screen where we can enter our local server.

Clicking Find manifest file will instruct ChatGPT to look for and read the ai-plugin.json and openapi.yaml files. The yaml file is validated before we can install the plugin and if there’s an issue with the file, we’ll get a warning telling us what’s wrong.

Let’s ask ChatGPT to look up a profile:

And it works!

We now have ChatGPT calling the Bluesky API when it thinks Bluesky can answer a user’s question. Albeit, it’s fairly limited right now. We can only look up user profiles and only if we provide them in the correct format of a Bluesky user handle.

In the next article, we’re going to take it a step further. We will expand our proxy app and integrate Bluesky’s javascript API client to make cleaner API calls, make calls to specific HTTP endpoints that aren’t in the normal spec to search, and learn to tweak our descriptions to make sure that ChatGPT knows what to do when it’s trying to compose calls.

Part 1: Writing the First Bluesky Plugin for ChatGPT

Torin Rozzelle — Sun, 07 May 2023 15:35:22 +0000

Earlier this week, I got an unexpected email that I was approved for the ChatGPT Plugins alpha. This is super exciting but the service I intended to develop for isn't yet in production. I've been writing some small projects for Bluesky to get to know the AT Protocol and wondered if I could use this opportunity to play around with both ChatGPT and the Bluesky API.

In this series of write-ups, I'm going to take you the first few steps of integrating the two and hopefully inspire some ideas, especially with federation around the corner

Plugin Structure

Let's first take a look the structure of an ChatGPT plugin. A plugin is intended to give ChatGPT access to an API by supplying the information that it needs to become, in OpenAI's words, 'an intelligent API caller'.

The plugin itself is made of metadata files that describe what endpoints are exposed. In its most minimal form, a plugin has three required files:

.well-known/ai-plugin.json
index.js
openai.yaml

index.js is mostly self-explanatory being the entry point of your plugin.

openai.yaml is an OpenAPI 3.0 specification file that defines the API and its endpoints as well as the structure of the data that is returned.

.well-known/ai-plugin.json is a manifest file, which tells ChatGPT information about the plugin. The manifest describes metadata about the plugin, the authorization method the plugin will use to access the api, and where the OpenAPI specification file can be found.

Writing a Plugin

Plugins can be developed either locally or remotely. For the purposes of this project, we're going to develop locally. The plugin development program is not really meant for people to develop for APIs that they do not control. When accessing a non-local resource, ChatGPT looks for the ai-plugin.json file at example.com/.well-known/ai-plugin.json.

We can get around this by developing locally and writing an HTTP proxy in Express that is going to act as middleware between ChatGPT and Bluesky, intercepting requests and making a call to Bluesky, doing some logic, and then returning the results.

To get started, use either the ChatGPT Plugins Quickstart or use the ChatGPT Typescript Starter that I've put together here.

If you're starting fresh, the first thing you're going to want to do is to install some dependencies:

npm install express http-proxy cors axios morgan dotenv

If you're using my starter, you can go ahead and install with:

npm install

Express provides the server and the routing for our local API.
http-proxy provides middleware that allows us to rewrite the path and pass the endpoint that we're calling locally through to the actual Bluesky endpoint.
cors is more middlware that will handle setting Cross-Origin Resource Sharing headers for our HTTP requests.
axios allows us to make asynchronous HTTP requests.
dotenv will allow us keep our secrets in a local .env file (which should always be .gitignore'd) and load them at run-time.

Create your .env file by using the .env-example:

ATPROTO_USER=bluesky_handle_without_@ # Ex: torin.bsky.social  
ATPROTO_PASS=preferably_an_app_password

and import the dependencies into index.js:

import express, { Request, Response, NextFunction } from 'express';  
import { createProxyMiddleware } from 'http-proxy-middleware';  
import cors from 'cors';  
import axios from 'axios';
import morgan from 'morgan';  
import dotenv from 'dotenv';  
import process from 'node:process';

We'll read the credentials from our .env file with dotenv and set up our environment:

dotenv.config()  

const targetAPI = 'https://bsky.social'; // API's base url
const apiIdentifier = process.env.ATPROTO_USER;  
const apiPassword = process.env.ATPROTO_PASS;

and outline a basic Express app:

const app = express();  
const port = 3005;  

// Tells express to use morgan for logging
// and the cors middleware
app.use(morgan('dev'));
app.use(cors())  

// Configure the proxy middleware  
const apiProxy = createProxyMiddleware('/api', {  
  target: targetAPI,  
  changeOrigin: true,  
  pathRewrite: {  
    '^/api': '/xrpc', // Change '/api' to /xrpc at the beginning of the path  
  },  
  onError: (err, req: Request, res) => {  
    console.error('Proxy error:', err);  
    res.status(500).json({error: 'Proxy Error'})  
  },  
});  

// Tells express to use the apiProxy middlware
app.use(apiProxy);

// Starts the server listening on port 3005
app.listen(port, () => {  
  console.log(`Proxy server listening on port ${port}`);  
});

What we're doing here is creating an express server that will listen on localhost:3005. We're telling express to use the cors middleware and morgan for logging. We then tell express to use the http-proxy middleware.

createProxyMiddleware abstracts away a bunch of work by taking each endpoint that we call locally and transforming it into a valid call to the Bluesky API. For example, a call to localhost:3005/api/getProfile becomes a call to https://bsky.app/xrpc/getProfile (not a real endpoint).

AT Protocol and XRPC

Bluesky's API is built on top of the Authenticated Transfer (AT) Protocol, a protocol built for large scale distributed social applications. I highly encourage you to read the protocol docs at atproto.com with the caveat that they are fairly out of date as of this writing and the protocol itself is still evolving. Things are expected to change.

The protocol uses its own idiomatic URI structure, identifiers, and server-to-server messaging protocol called XRPC. I'm not going to do a deep drive here but for the purposes of this write-up, you mostly need to know that XRPC is a thin wrapper around HTTP that uses GET and POST to exchange data and supports both structured JSON data and binary blobs.

AT Protocol's XRPC methods and record types are documented in schemas called Lexicons, which are defined in reverse DNS order like app.bsky.feed.getPosts or com.atproto.server.createSession. The two lexicon families we'll be working with are com.atproto, which defines methods and record types native to the protocol and app.bsky, which defines Bluesky-specific methods and record types.

Returning to our program, what our HTTP proxy allows us to do is to make a request like localhost:3005/api/app.bsky.feed.getPosts and have that transformed into bsky.app/xrpc/app.bsky.feed.getPosts, receiving the response to the proxy which is then relayed back to ChatGPT.

Authenticating

One thing that's missing from our proxy is authentication. We run into an early adoption problem here since ChatGPT does not yet support user-level authentication for plugins and Bluesky's authentication does not yet support service-level authentication (i.e. API keys) or OAuth.

For the moment, we're going to authenticate with a user account in our proxy app itself and, because we're developing locally, instruct ChatGPT that no authentication is required. This is not something that you would ever want to do in a production environment.

We're going to add two authentication functions:

// Function to authenticate with Bluesky's API  
async function authenticate(): Promise<string> {  

    const params = {  
    "identifier": apiIdentifier,  
    "password": apiPassword  
  }  

  // Make a POST request to createSession and wait for the response
  const response = await axios.post(`${targetAPI}/xrpc/com.atproto.server.createSession`, params, {});  

  // Return the JWT from the response  
  return response.data.accessJwt;
}  

// Function to insert Auth headers that will be used for future requests
async function addAuthToken(req: Request, res: Response, next: NextFunction) {  

  try {  
    const token = await authenticate();  
    req.headers['Authorization'] = `Bearer ${token}`; 

    next();  

  } catch (err) {  
    console.error('Authentication error: ', err);  
    res.status(500).json({ error: 'Authentication error'});  
  }  
}

app.use(addAuthToken);

authenticate() is going to make an HTTP POST request to the com.atproto.server.createSession endpoint with a JSON payload that includes our username and password. A successful response contains a JSON Web Token which is returned to the calling addAuthToken(), which creates an Authorization header with the JWT.

app.use(addAuthToken) tells Express to use the middleware function and the call to next() in addAuthToken proceeds to the next method in the chain.

At this point, we should be able to make a call to any of the Bluesky endpoints with the correct parameters and get a valid response.

Let's check that by making a call to the app.bsky.unspecced.getPopular endpoint, which returns the most popular posts at the moment:

curl 'localhost:3005/api/app.bsky.unspecced.getpopular' | jq '.’

and we get

Great! We now have a working proxy to the Bluesky API.

In the next article, we're going to build the ai-plugin.json and openapi.yaml files that will tell ChatGPT how to use our API, register our plugin to run locally, and pose our first question in the chat.