The Open API is set as the Standard for ChatGPT Plugins

What is ChatGPT Plugin

Recently, OpenAI announced a major update: ChatGPT now supports Plugin capabilities. When interacting with ChatGPT in natural language, users can choose to use plugins. Through plugin extensions, ChatGPT can achieve the following capabilities:

• Retrieve real-time information, such as sports scores, stock prices, and the latest news.
• Retrieve knowledge base information, such as company documents and personal notes.
• Perform actions on behalf of the user, such as booking flights and ordering food.

For example, if a user wants to use ChatGPT to search for hotel information in a certain city, they only need to install and allow the use of a hotel search plugin, and then they can obtain information such as the name, price, rating, and location of the hotel through simple dialogue.

If a user wants to use ChatGPT to learn a programming language, they only need to install and allow the use of a programming tutorial plugin, and then they can master the basic knowledge and skills of programming through interactive Q&A.

Openai is offering a web browser plugin and a code execution plugin, and open-sourcing the code for a retrieval plugin. Plugins are very experimental still but we think there's something great in this direction; it's been a heavily requested feature.                                                        

-Sam Altman，CEO of OpenAI

The Technology Behind the Plugin

Plugin developers specify one or more open API endpoints (referring to a specific API) through a standard manifest file and an API document file in OpenAPI specification format. These files define the functions of the plugin, allowing ChatGPT to read these files and call the APIs defined by the developers. In short, the AI model acts as the caller of the intelligent API. Given the API specification and a natural language description of when to use the API, the model will actively call the API to perform the operation.

The Process from Building to Using Plugins

As of March 30, 2023, ChatGPT plugins are still in a limited alpha version stage, so you need to join the waiting list to queue for access. During the alpha version period, OpenAI also promises to work closely with users and developers to iterate the plugin system, so the final plugin functionality may also change, which is an important point to note if you want to experience it in advance and become a plugin developer.

Create a Manifest file

• Host the file at yourdomain.com/.well-known/ai-plugin.json
• The file contains metadata about the plugin (name, logo, etc.), authentication information (authentication type, OAuth URL, etc.), and an API document file in OpenAPI specification format.
• The model will see the fields described in the OpenAPI specification, which can be used to provide natural language descriptions for these fields.
• It is recommended to initially expose only 1-2 endpoints and use the minimum number of parameters to minimize the length of the text. Plugin descriptions, API requests, and API responses are inserted into the conversation with ChatGPT. Too much content will affect the model's context length limit.

Register the plugin in the ChatGPT UI

• ChatGPT UI website: https://chat.openai.com/
  Select the plugin model from the top drop-down list, then select "Plugins", "Plugin Store", and finally "Install an unverified plugin" or "Develop your own plugin".
• If authentication is required, you need to provide OAuth 2 client_id and client_secret or API Key.

Activate Your Plugin

• Users must manually activate your plugin in the ChatGPT UI (ChatGPT will not use your plugin by default).
• During the alpha testing period, plugin developers will be able to share their plugins with 15 other users (currently only other developers can install unverified plugins). Over time, OpenAI will roll out a way to submit your plugin for review to expose it to the entire ChatGPT user base.
• If authentication is required, users will be redirected to your plugin via OAuth; you can also choose to create a new account here.
• In the future, OpenAI may build features to help users discover useful and popular plugins.

Start the Conversation

• OpenAI will include a concise description of your plugin in the messages sent to ChatGPT, but end users will not see it. This will include the plugin description, endpoints (specific APIs), and examples.
• When users ask relevant questions, if it seems appropriate, the model may choose to make API calls from your plugin. For POST requests, OpenAI requires developers to build a user confirmation flow.
• The model will merge the API results into its response to the user.
• The model's response may contain links returned from the API call. These will appear as rich previews (using the OpenGraph protocol, where OpenAI extracts site_name, title, description, image, url fields).

For more details about the plugin, you can refer to the official documentation.

Plugins and OpenAPI

In the above article, we introduced the core capabilities and basic technical implementation principles of plugins. It is mentioned that if you want the AI model to act as an intelligent caller of your API through the plugin, you must place your API's OpenAPI specification-formatted documentation in a manifest file. This is because only when your API documentation conforms to this specification can the AI model understand and successfully make calls to your API.
Why did OpenAI adopt the OpenAPI specification as the standard format for its plugin capabilities to call APIs? To understand this, it is necessary to know what the OpenAPI specification is and how it was formed. After understanding these contents, it will be clear why OpenAI chose the OpenAPI specification as the standard for the plugin capabilities of its flagship product, ChatGPT.

What is the OpenAPI Specification?

The OpenAPI Specification (OpenAPI) is an open, standardized, machine-readable API description format that helps developers create, test, publish, and maintain APIs quickly. OpenAPI can also be used to generate API documentation, client code, server code, etc.
The specification of OpenAPI is developed and maintained by the OpenAPI Initiative (OAI), and the latest version is 3.1.0. The OpenAPI specification uses JSON or YAML language to define API metadata, paths, parameters, responses, security, and other information. The OpenAPI specification is a universal and language-agnostic interface that enables both humans and computers to discover and understand the capabilities of an API without accessing source code, additional documentation, or network traffic inspection.

Origin of the OpenAPI Specification

The OpenAPI specification was created by Tony Tam in 2009 when he was an engineer at Wordnik. He wanted to describe the Wordnik online dictionary JSON API, so he created a specification called Swagger. Swagger went through several iterations and improvements in the following years. In 2015, SmartBear Software acquired the Swagger specification and donated it to a new organization under the Linux Foundation called the OpenAPI Initiative (OAI). The OAI, composed of multiple companies, aims to promote and maintain the development of the OpenAPI specification.
In 2016, the Swagger specification was officially renamed the OpenAPI specification and migrated to a new GitHub repository. Since then, the OpenAPI specification has been continuously updated and improved.

Code First vs API First

Now we can understand the importance of having a compliant API documentation. With this documentation, both humans and machines can better understand your API. In the API development process, there are generally two common ways to generate OpenAPI-compliant documentation:

1. Code First: Prioritize API and business code development. After development and passing unit tests, technical personnel write OpenAPI specification documentation based on the actual code. This work mode is known as "Code First."
2. API First: Prioritize API definition and write documentation based on the OpenAPI specification. Actual code development is then done based on this specification documentation. This work

Conclusion

Therefore, if you adopt an API First workflow and define this capability in advance by creating an OpenAPI specification document before the development work begins, there are several obvious benefits:

• If you are a team developing this plugin, all members of your team will reach a consensus because of the OpenAPI specification document that was created first. Everyone knows clearly what their development goals are, avoiding the tragedy of actual development code deviating from the target.
• You can simulate the results of ChatGPT after calling it by setting up a mock server for this interface to debug and understand the actual effect, rather than waiting until everything is ready to see if the development effect meets expectations.
• Q&A work can start synchronously with code development, writing test cases while developing code, accelerating your plugin release and iteration rhythm.

The above is a brief introduction to ChatGPT plugins, OpenAPI, and API First. We hope this article can help you develop your ChatGPT plugin more efficiently.