How to optimise API specs for plugins

We are experimenting a lot at Blobr with plugins and managed to connect a lot of tool we use internally like hubspot, notion, typeform, etc. It is fascinating that you can request any SaaS in ChatGPT directly.

We had the following key learnings:

An API product approach with fewer Calls, More Arguments

When designing your API, it’s often more effective to have fewer endpoints with more query parameters. The golden number seems to be about 3 or 4 endpoints max. This approach simplifies the API and makes it easier for the ChatGPT plugin to understand and interact with. For example, instead of having separate endpoints for stories, comments, polls, etc., you could have a single /items endpoint with various query parameters to control the output.

Learn by Iteration

Sometimes, ChatGPT might “hallucinate” parameters that don’t exist in your API. Instead of seeing this as a problem, consider it as a hint for potential improvements. For instance, if ChatGPT frequently adds a non-existent sort_order parameter, it might be a good idea to implement it. Iterating your API based on these insights can lead to a more effective integration.

Be Terse

Both your OpenAPI specification and your API responses should be as concise as possible. While it’s important to be descriptive, short and to-the-point descriptions tend to work better with ChatGPT. Also, if your API responses are too long, it might lead to hallucinations or the model ignoring your response. So, keep it short and sweet!

Be Tolerant of Inputs

ChatGPT is a language-driven model and might not be as precise with numbers as a human user would be. Therefore, it’s a good idea to avoid things like UNIX timestamps in your APIs. Instead, use standardized date formats like ISO8601, or even better, accept natural language inputs. Using parsers like dateparser in Python can help process natural language dates and times.

Set Reasonable Defaults

Setting reasonable default values for your endpoints can improve the user experience. For instance, if you have a limit parameter for the /items endpoint, consider setting a default value that provides a balance between response length and usefulness.

Use ChatGPT to Help You

ChatGPT can be a valuable tool in the development of your API. Not only can it help write code for your API implementation, but it can also create concise descriptions of APIs from lengthy documentation. This can be a great starting point for your project.

What are your key learnings creating your plugins?

4 Likes

Great topic, thanks for posting.

Can you provide some OAS examples?

If you can, as a suggestion they might appear better using Hide Details.

In the reply editor, the top row with icons is a gear at the end, under the gear is the option Hide Details.

Hide details example (Click triangle to expand)

This text will be hidden

It can contain lots of lines that can be easily hidden to make reading the main content more enjoyable.













1 Like

Just getting my feet in the water with plugins so this may already be obvious.

I develop in Prolog specifically SWI-Prolog, as a round robin check of the code and OAS, prompt ChatGPT to generate the code from the OAS and also generate an OAS from the code, adjusting as needed. Learned this by first creating plugins with Python then using just the OAS to create the needed SWI-Prolog code.

In doing so also realized that the OAS does not need to include details about .well-known\ai-plugin.json and openapi.yaml. That CORS, CORS preflight and HTTP option method do not need to be in the OAS. Then developing the OAS for two different languages and having ChatGPT generate the code often exposes overlooked details that can be included in the OAS.

That the fields contact_email and legal_info_url can be empty strings, E.g. "".

That reviewing the OAS of other plugins if very helpful. These can easily be obtained for review by cloning GitHub - sisbell/chatgpt-plugin-store: ChatGPT Plugin Store List and then using file search of the specs directory with an editor like NotePad++.

For each prompt an additional info box will appear, e.g.

image

Clicking the drop down will reveal details for the values being sent. Clicking the info icon in the upper right will show which API endpoint is being used and , e.g.

image


06/03/20223

Dev Tools, which includes a right panel in the ChatGPT conversation page, now displays a TypeScript summary of the generated API used with ChatGPT. This was an unexpected benefit.

1 Like

I’ve using more than double this number consistently for the past month in my plugin, and plan on adding more. How well it works is a prompt engineering problem. ChatGPT devtools shows the prompt and has been quite useful in helping me debug any issues with the endpoints.

Some of my notes on the “Plugin Prompt”:

4 Likes

Thanks a lot for sharing this. We keep on optimising this at Blobr.