In this article we will look at how to read API documentation.
Every good API should be well documented and be fairly easy to understand, once you know how to read it properly.
Quick Examples
Below is an example from RapidAPI that shows what each part of their docs mean.
Below is an example from Huggingface that shows what each part of their docs mean.
OpenAI API documentation
We will firstly take a look at OpenAI’s documentation as their docs are clear and well written: https://beta.openai.com/docs/api-reference/introduction
The Introduction section tells us we “can interact with the API through HTTP requests from any language”. Perfect.
WordPress is built with PHP, which uses cURL to make the HTTP requests. We can simply ignore anything they say about Python, Node or other languages. We are only interested in cURL, PHP or HTTP, which we will see a little further down.
Scrolling down to the Authentication section will tell us how we need to authenticate ourselves to the API.
OpenAI uses the ‘Bearer’ method with your API key. But for other API’s, authentication could be via a secret key or a user:password combo or some other method. Most docs will have an Authentication section.
The OpenAI docs tell us that we need to include the API key in an Authorization header as shown below. The word Authorization is the ‘name’ of the header and the Bearer YOUR_API_KEY is the corresponding ‘value’. The colon is what separates the name:value.
To add this name:value pair in WPGetAPI, you simply need to fill in the name and value within the Headers fields as shown below. Simple!
You can also see below that you can add other headers into this section, such as the ‘Content-Type’ header.
Reading curl requests
If you scroll further down to the Making Requests section of the OpenAI docs, we can see a bunch code that might look a little odd. This is basically a list of cURL commands that will make a request to the https://api.openai.com/v1/completions API endpoint.
cURL is a command-line tool that allows us to make HTTP requests, which is really all an API request is. Some API docs will show other languages or provide an option to choose the language that you view the docs in, but for us we want to be looking at either cURL, HTTP or PHP commands usually.
The 4 lines below give us everything we need to make a request to the API.
How do we read this?
The word curl as well as the -H and the -D flags tell us where we need to add the pieces of information that follow them. Unfortunately, curl commands can be written in a number of different ways, so we need to look for the ‘clues’ that tell us what we need to do.
Let’s break down each line and see what they mean.
Line 1: The word curl on it’s own, followed directly by the URL will tell us we need to send the request to https://api.openai.com/v1/completions
Line 2: The -H flag indicates that we need to add Content-Type:application/json as a header like we did earlier.
Line 3: Again we have the -H flag that indicates we add the Authorization as a header
Line 4: The -d flag is short for -data and tells us we need to send the data in this line within the Body POST fields. And because we are sending data in the Body POST fields, we know that this will be a POST request.
Setting up this OpenAI endpoint using WPGetAPI should look something like the below.
You will also notice that we have set the temperature as float(0.7) – this float() keyword is a special function that we can add to the parameters. It will simply send the value of 0.7 as a float value rather than a string, as OpenAI requires it this way.
Once saved, you can hit the ‘Test Endpoint’ button to see if it was successful.