Past OpenAPI

2023-09-11 07:26:14

Not all documentation is created equal. Based on the favored classification, there are 4 doc varieties: tutorials, how-to guides, technical references, and explanations.

OpenAPI, the de facto normal for documenting APIs, is an honest reference-style documentation (and shopper code generator, after all). However it could possibly’t function a great how-to or tutorial.

On this article, I’ll introduce a concise and readable strategy to write interactive tutorials and how-tos for any HTTP API (REST, RPC, or different fashion). And for that (shock, shock), we are going to depend on the HTTP protocol itself.

A crash course in HTTP messages

HTTP/1.x is a plain-text protocol that describes the communication between the shopper and the server. The shopper sends messages like this:

POST /something/chat HTTP/1.1
host: httpbingo.org
content-type: utility/json
user-agent: curl/7.87.0

{
    "message": "Hiya!"
}

And receives messages like this in response:

HTTP/1.1 200 OK
date: Mon, 28 Aug 2023 07:51:49 GMT
content-type: utility/json

{
    "message": "Hello!"
}

HTTP/2, the successor to HTTP/1.1, is a binary protocol. Nevertheless, all instruments (such because the browser devtools or curl) show HTTP/2 messages in plain textual content (similar to HTTP/1.1), so we will safely ignore this reality for our functions.

It is simple to learn HTTP requests and responses when you get used to it.

HTTP request consists of three important sections:

Request line:

POST /something/chat HTTP/1.1

The technique (POST) defines the operation the shopper desires to carry out.
The path (/something/chat) is the URL of the requested useful resource (with out the protocol, area and port).
The model (HTTP/1.1) signifies the model of the HTTP protocol.

Request headers:

host: httpbingo.org
content-type: utility/json
user-agent: curl/7.87.0

Every header is a key-value pair that tells the server some helpful details about the request. In our case it is the hostname of the server (httpbingo.org), the kind of the content material (utility/json) and the shopper’s self-identification (user-agent).

Request physique:

{
    "message": "Hiya!"
}

The precise information that the shopper sends to the server.

The HTTP protocol is stateless, so any state have to be contained inside the request itself, both within the headers or within the physique.

HTTP response additionally consists of three important sections:

Standing line:

HTTP/1.1 200 OK

The model (HTTP/1.1) signifies the model of the HTTP protocol.
The standing code (200) tells whether or not the request was profitable or not, and why (there are various standing codes for different situations).
The standing message is a human-readable description of the standing code. HTTP/2 doesn’t have it.

Response headers:

date: Mon, 28 Aug 2023 07:51:49 GMT
content-type: utility/json

Much like request headers, these present helpful details about the response to the shopper.

Response physique:

{
    "message": "Hello!"
}

The precise information that the server sends to the shopper.

There may be rather more to the HTTP protocol, however this primary data is sufficient to cowl most of API use circumstances. So let’s transfer on.

Utilizing HTTP to doc API utilization

We’re going to take an HTTP request:

POST /something/chat HTTP/1.1
host: httpbingo.org
content-type: utility/json
user-agent: curl/7.87.0

{
    "message": "Hiya!"
}

And modify it just a bit bit:

embrace the total URL within the request line as an alternative of the trail;
take away the protocol model.

POST http://httpbingo.org/something/chat
content-type: utility/json

{
    "message": "Hiya!"
}

This format is ideal for API utilization examples. It is concise and readable, but formal sufficient to be executed programmatically (immediately from the documentation, as we’ll see shortly).

Writing an interactive API information

As an alternative of telling you easy methods to write an interactive API tutorial, I will present you one. We’ll use Gists API for example. It is a compact and helpful GitHub service for storing code snippets (referred to as “gists”).

Gists are fairly helpful when a full-blown Git repository is an excessive amount of.

Even in case you are not a GitHub person, you continue to have entry to the Gists API.

Studying gists

Let’s check out the public gists of my pal Redowan (person rednafi). The response will be fairly chatty, so we’ll solely choose the three most up-to-date (per_page = 3):

GET https://api.github.com/customers/rednafi/gists?per_page=3
settle for: utility/json

A household of non-standard x-ratelimit headers inform us how GitHub limits our requests:

There’s a complete variety of x-ratelimit-limit requests out there per hour.
We have already used x-ratelimit-used requests.
So there are x-ratelimit-remaining requests left.

We have to regulate these to ensure we do not exceed the quota.

We are able to use a mixture of web page and per_page question parameters to pick out a slice of gists. For instance, listed here are gists 10-15:

GET https://api.github.com/customers/rednafi/gists?web page=3&per_page=5
settle for: utility/json

Be aware that GitHub supplies navigation hyperlinks within the hyperlink header:

hyperlink:
    <https://api.github.com/person/30027932/gists?web page=2&per_page=5>; rel="prev",
    <https://api.github.com/person/30027932/gists?web page=4&per_page=5>; rel="subsequent",
    <https://api.github.com/person/30027932/gists?web page=7&per_page=5>; rel="final",
    <https://api.github.com/person/30027932/gists?web page=1&per_page=5>; rel="first"

That is considerate of them!

Okay, now let’s check out the particular gist with id 88242fd822603290255877e396664ba5 (this one is mine; let’s not trouble Redowan anymore):

GET https://api.github.com/gists/88242fd822603290255877e396664ba5
settle for: utility/json

We are able to see that there’s a greet.py file written within the Python language with a sure content material:

class Greeter:
    def __init__(self, greeting):
        self.greeting = greeting

    def greet(self, who):
        print(f"{self.greeting}, {who}!")

gr = Greeter("Hiya")
gr.greet("world")

(yep, you may as well create interactive Python examples!)

Curiously, the gist has a historical past. It seems that each time you edit a gist, GitHub creates a brand new model, whereas additionally retaining earlier variations.

Let’s get the earliest revision, which has a model = 4c10d27cfb163d654745f1d72f2c7ce14225b83b (a bit lengthy, I do know):

GET https://api.github.com/gists/88242fd822603290255877e396664ba5/4c10d27cfb163d654745f1d72f2c7ce14225b83b
settle for: utility/json

The code within the gist was a lot less complicated again then:

msg = "Hiya, world!"
print(msg)

Modifying gists

Okay, so we all know easy methods to record gists for a person, easy methods to get a selected gist, and even easy methods to get a selected revision. Now let’s create a brand new gist!

POST https://api.github.com/gists
content-type: utility/json
settle for: utility/json

{
    "description": "Greetings in Markdown",
    "public": true,
    "recordsdata":{
        "README.md":{
            "content material":"Hiya, world!"
        }
    }
}

What’s that? Now we have a 401 Unauthorized error. The response physique explains: “requires authentication” and even supplies a hyperlink to the documentation (oh, I simply love GitHub APIs).

Understandably, GitHub doesn’t permit nameless customers to create new gists. Now we have to authenticate with an API token.

If you need the next examples to work, enter your API token within the discipline beneath. You possibly can create one with a ‘gist’ scope within the GitHub settings.

After you enter the token beneath, it is going to be saved domestically within the browser and won’t be despatched wherever (besides to the GitHub API if you click on the Run button).

Let’s strive once more, this time with an authorization header.

Be aware the public parameter. The service helps “secret” gists (public = false), but it surely’s the “safety by obscurity” sort of secrecy. Secret gists don’t present up within the “GET gists” API technique, however they’re nonetheless accessible by id, even by nameless customers.

POST https://api.github.com/gists
content-type: utility/json
settle for: utility/json
authorization: bearer {token}

{
    "description": "Greetings in Markdown",
    "public": true,
    "recordsdata":{
        "README.md":{
            "content material":"Hiya, world!"
        }
    }
}

I haven’t got a token, simply present me the outcomes

HTTP/1.1 201 
cache-control: non-public, max-age=60, s-maxage=60
content-length: 3758
content-type: utility/json; charset=utf-8
etag: "819f6b4f728843abcb50ad63da200a4c110245585b3eb1c0f59a5ebe86c8ecf5"
location: https://api.github.com/gists/b17474320a629af38255c0a6efbc72b9
x-accepted-oauth-scopes: 
x-github-media-type: github.v3
x-github-request-id: E8B5:8EDA:511F73:51AC33:64EE0266
x-oauth-scopes: gist
x-ratelimit-limit: 5000
x-ratelimit-remaining: 4997
x-ratelimit-reset: 1693323114
x-ratelimit-resource: core
x-ratelimit-used: 3

{
  "url": "https://api.github.com/gists/b17474320a629af38255c0a6efbc72b9",
  "forks_url": "https://api.github.com/gists/b17474320a629af38255c0a6efbc72b9/forks",
  "commits_url": "https://api.github.com/gists/b17474320a629af38255c0a6efbc72b9/commits",
  "id": "b17474320a629af38255c0a6efbc72b9",
  "node_id": "G_kwDOACz0htoAIGIxNzQ3NDMyMGE2MjlhZjM4MjU1YzBhNmVmYmM3MmI5",
  "git_pull_url": "https://gist.github.com/b17474320a629af38255c0a6efbc72b9.git",
  "git_push_url": "https://gist.github.com/b17474320a629af38255c0a6efbc72b9.git",
  "html_url": "https://gist.github.com/nalgeon/b17474320a629af38255c0a6efbc72b9",
  "recordsdata": {
    "README.md": {
      "filename": "README.md",
      "sort": "textual content/markdown",
      "language": "Markdown",
      "raw_url": "https://gist.githubusercontent.com/nalgeon/b17474320a629af38255c0a6efbc72b9/uncooked/5dd01c177f5d7d1be5346a5bc18a569a7410c2ef/README.md",
      "measurement": 13,
      "truncated": false,
      "content material": "Hiya, world!"
    }
  },
  ...
}

HTTP standing 201 Created signifies that a brand new gist has been created because of our request.

Okay, now we will replace a gist utilizing its id (do not forget to switch the {gist_id} within the request line with the precise id worth):

PATCH https://api.github.com/gists/{gist_id}
content-type: utility/json
settle for: utility/json
authorization: bearer {token}

{
    "description": "Greetings in Markdown",
    "public": true,
    "recordsdata":{
        "README.md":{
            "content material":"¡Hola, mundo!"
        }
    }
}

I haven’t got a token, simply present me the outcomes

HTTP/1.1 200 
cache-control: non-public, max-age=60, s-maxage=60
content-type: utility/json; charset=utf-8
etag: W/"989eaec7cdb50ba6441e77ea2defba257b98a535f26c2ba6062f152ceffb2d77"
x-accepted-oauth-scopes: 
x-github-media-type: github.v3
x-github-request-id: E8B5:8EDA:5188AA:52163F:64EE027F
x-oauth-scopes: gist
x-ratelimit-limit: 100
x-ratelimit-remaining: 98
x-ratelimit-reset: 1693323129
x-ratelimit-resource: gist_update
x-ratelimit-used: 2

{
  "url": "https://api.github.com/gists/b17474320a629af38255c0a6efbc72b9",
  "forks_url": "https://api.github.com/gists/b17474320a629af38255c0a6efbc72b9/forks",
  "commits_url": "https://api.github.com/gists/b17474320a629af38255c0a6efbc72b9/commits",
  "id": "b17474320a629af38255c0a6efbc72b9",
  "node_id": "G_kwDOACz0htoAIGIxNzQ3NDMyMGE2MjlhZjM4MjU1YzBhNmVmYmM3MmI5",
  "git_pull_url": "https://gist.github.com/b17474320a629af38255c0a6efbc72b9.git",
  "git_push_url": "https://gist.github.com/b17474320a629af38255c0a6efbc72b9.git",
  "html_url": "https://gist.github.com/nalgeon/b17474320a629af38255c0a6efbc72b9",
  "recordsdata": {
    "README.md": {
      "filename": "README.md",
      "sort": "textual content/markdown",
      "language": "Markdown",
      "raw_url": "https://gist.githubusercontent.com/nalgeon/b17474320a629af38255c0a6efbc72b9/uncooked/95975f3d0bac707ce4355dfc4a7955310d212fac/README.md",
      "measurement": 14,
      "truncated": false,
      "content material": "¡Hola, mundo!"
    }
  },
  ...
}

It now greets us in Spanish ????????

Superb. Lastly, let’s delete a gist:

DELETE https://api.github.com/gists/{gist_id}
settle for: utility/json
authorization: bearer {token}

I haven’t got a token, simply present me the outcomes

HTTP/1.1 204 
x-accepted-oauth-scopes: 
x-github-media-type: github.v3
x-github-request-id: E8B5:8EDA:51E584:5273CC:64EE027F
x-oauth-scopes: gist
x-ratelimit-limit: 5000
x-ratelimit-remaining: 4996
x-ratelimit-reset: 1693323114
x-ratelimit-resource: core
x-ratelimit-used: 4

HTTP standing 204 No Content material means we deleted the gist, so GitHub has nothing extra to inform us about it. It is a little bit unhappy to see it go, however we will all the time make one other one, proper?

The Gists API has different helpful options, however they’re past the scope of this tutorial. Listed below are the features we have coated:

Listing person gists.
Get a selected gist, or a selected revision of a gist.
Create a brand new gist.
Replace an present gist.
Delete a gist.

Now strive managing your gists! You possibly can all the time use this text as a playground.

Implementation

To run the API examples as we did within the earlier part, you will want a little bit of JavaScript that does the next:

Parses the HTTP request instance.
Calls the API.
Shows the consequence.

It is all the time good when a playground does not want a server.

Since we have restricted ourselves to a small subset of HTTP request capabilities, parsing is pretty simple:

// parse parses the request specification.
perform parse(textual content) {
    const strains = textual content.cut up("n");
    let lineIdx = 0;

    // parse technique and URL
    const methodUrl = strains[0].cut up(" ").filter((s) => s);
    const [method, url] =
        methodUrl.size >= 2 ? methodUrl : ["GET", methodUrl[0]];
    lineIdx += 1;

    // parse headers
    const headers = {};
    for (let i = lineIdx; i < strains.size; i++) {
        const line = strains[i].trim();
        if (line === "") {
            break;
        }
        const [headerName, headerValue] = line.cut up(":");
        headers[headerName.trim()] = headerValue.trim();
        lineIdx += 1;
    }

    // parse physique
    const physique = strains.slice(lineIdx + 1).be part of("n");

    return { technique, url, headers, physique };
}

const spec = parse(`GET https://httpbingo.org/uuid`);
console.log(JSON.stringify(spec, null, 2));

Calling the API and displaying the outcomes is trivial — simply use the Fetch API and show the consequence as plain textual content:

// execCode sends an HTTP request based on the spec
// and returns the response as textual content with standing, headers and physique.
async perform execCode(spec) {
    const resp = await sendRequest(spec);
    const textual content = await responseText(resp);
    return textual content;
}

// sendRequest sends an HTTP request based on the spec.
async perform sendRequest(spec) {
    const choices = ;
    return await fetch(spec.url, choices);
}

// responseText returns the response as textual content
// with standing, headers and physique.
async perform responseText(resp) {
    const model = "HTTP/1.1";
    const textual content = await resp.textual content();
    const messages = [`${version} ${resp.status} ${resp.statusText}`];
    for (const hdr of resp.headers.entries()) {
        messages.push(`${hdr[0]}: ${hdr[1]}`);
    }
    if (textual content) {
        messages.push("", textual content);
    }
    return messages.be part of("n");
}

const spec = {
    technique: "GET",
    url: "https://httpbingo.org/uuid",
};

const textual content = await execCode(spec);
console.log(textual content);

Fetch API works within the browser, so there isn’t a intermediate server concerned. The one nuance is that the documentation should both be on the identical area because the API itself, or the API should permit cross-domain requests. However even when that is not the case, you may all the time proxy the requests — it is not an excessive amount of work.

If you need an out-of-the-box resolution, I’ve written a easy library that helps each JavaScript and Fetch API playgrounds:

codapi-js

Ideally, I might like most documentation to be interactive. Not simply API guides, however every part from algorithms (like hashing) to programming languages (like Go or Odin) to databases (like SQLite), frameworks and instruments, and even particular person packages.

And (shameless plug right here!) I am constructing a platform that permits simply that — simply embeddable code playgrounds for documentation, on-line training, and enjoyable. Test it out in case you are :

codapi

And please attempt to write an interactive information the subsequent time you develop an API!