Optic's Echo API: Free, Fake APIs for All

Nate Meyer 2023-10-26

Lately I’ve spent a lot of time working on Optic’s Capture feature and writing documentation around integrations between Optic and other API tools. What has been consistently awkward is choosing an API to demonstrate with Optic Capture. Looking through our blogs posts and documentation, you’ll find examples using a Go API (opens in a new tab), our Bookstore Example (opens in a new tab) (which uses some demo endpoints built into our backend API), or 3rd party APIs.

Having variety in our examples has been useful for trying to reach the broadest audience, but dependence on example code repositories, additional tooling, or 3rd party APIs made showing the utility of Capture more difficult than it needed to be.

This led me to think about what a minimal demo for Capture could look like. My immediate thought was an “echo” server, similar to Postman’s own Echo API (opens in a new tab). While our ultimate goal is the same as Postman’s Echo API—facilitate exploring the tool without needing a “real” API—Optic’s needs are slightly different. We wanted to be able to not only mock an API, but also specify what the response looks like. This would allow Capture to both generate the requests as well as analyze their responses—all without the need for a local example repo or external API.

A couple conversations and a little hacking later, Optic’s Echo API was born. The server itself is MIT licensed and you can view the source on GitHub (opens in a new tab).

Using Optic’s Echo API

Using the service is very simple—It responds to any endpoint and any HTTP method with details you provide via specific headers.

It’s available at: https://echo.o3c.org (opens in a new tab)

A minimal request to the service with curl (opens in a new tab) looks like this,

➜ curl -i https://echo.o3c.org/ -H 'x-response-json:{"hello": "world"}'
HTTP/2 200
date: Mon, 23 Oct 2023 16:19:37 GMT
content-type: application/json; charset=utf-8
content-length: 17
 
{"hello": "world"}

Demonstrating Optic Capture with the Echo API

The Echo API works nicely with our existing capture features in the optic.yml file. You can quickly kick the tires on Optic Capture without needing a separate API or tools other than Optic. Let’s try it out!

Create a new temp directory,

➜ cd $(mktemp -d) && pwd
/var/folders/fw/fhg4z0xd0nlghrg32_myv_z00000gn/T/tmp.I7vvynPNqv

Generate an optic.yml file,

➜ optic capture init openapi.yml
✔ Wrote capture config to optic.yml

If you are using Optic version ≥ 0.50.12, your optic.yml will look similar to this,

capture:
  openapi.yml:
    server:
      url: https://echo.o3c.org
    requests:
      send:
        - path: /users
          headers:
            # this is the response body we will echo
            x-response-json: '[{"id":0, "name":"aidan"}]'

If yours doesn’t, replace its contents with the above.

Run optic capture openapi.yml --update interactive,

➜ optic capture openapi.yml --update interactive
Initializing OpenAPI file at openapi.yml
✔ Finished running requests
 
Learning path patterns for unmatched requests...
> /users/
✔ Is this the right pattern for GET /users/ › yes
Documenting new operations:
✔ GET /users/

Take a look at the openapi.yml file that has been generated. You’ll see the /users endpoint has been added and response body has been documented.

info:
  title: Untitled service
  version: 1.0.0
openapi: 3.1.0
paths:
  /users:
    get:
      responses:
        "200":
          description: 200 response
          content:
            application/json; charset=utf-8:
              schema:
                $ref: "#/components/schemas/GetUsers200ResponseBody"
components:
  schemas:
    GetUsers200ResponseBody:
      type: array
      items:
        type: object
        properties:
          id:
            type: number
          name:
            type: string
        required:
          - id
          - name

Any manual changes you make, like updating info.title, will be preserved on future runs. You're free to manually edit the file as you see fit.

Let’s try adding another endpoint. Add the following snippet to the requests.send section of the optic.yml file,

- path: /users/create
  method: POST
  data:
    name: nic
  headers:
    x-response-json: '{"id":1, "name":"nic"}'
	# you can also dictate the response code
    x-response-code: "201"

Run optic capture again,

➜ optic capture openapi.yml --update automatic
✔ Finished running requests
...
Learning path patterns for unmatched requests...
Documenting new operations:
✔ POST /users/create

Once again, take a look at the openapi.yml file and notice that the /users/create endpoint has been added. We even documented the request body this time—cool! Try modifying the existing endpoints, or making additional changes and see what happens. The Echo API makes it very simple to test a variety of scenarios.

When you’re ready to try Optic with your API, take a look at the configuration reference (opens in a new tab) for complete details about setting up your optic.yml file.

Free and Open

While we created the Echo API service to scratch our own itch, it’s available to the public. If you have a use for it, be our guest! We’d love to hear your opinion (opens in a new tab) and any use cases you come up with.