API Endpoint Discovery, Part I

So, you have a pre-existing API, with 1-500 endpoints, and no Swagger / RAML / JSON Schema for it. How do you get these endpoints described and covered by one or more of these specifications?

Option 1 Manually write the spec for each endpoint. This is very time consuming, and error prone.

Option 2 Manually define each endpoint in a higher level designer, like StopLight, and then export to a specification. Less time consuming and error prone, but still not ideal.

Option 3 Use the StopLight API Designer + Prism Proxy to automatically generate endpoint definitions, simply by sending HTTP traffic to your API.

In this post, we're going to describe the basics of option 3. The StopLight API Designer + Prism Proxy combo is the fastest, and most effective, method of generating Swagger / RAML / JSON Schema for a pre-existing API.

First, a short video of it in action. The first half of the video focuses on setup, so if you're just interested in the juicy bits, skip to the second half.

So what is happening here? We are sending HTTP traffic through the local instance of the Prism API Proxy. By default, the proxy runs on http://localhost:4010. Back in the API Designer, for our development environment, we have defined the API Host as http://localhost:3000. This is where the simple Todos API is running on our computer.

When a request comes into the proxy (localhost:4010), it transparently forwards the request to the API Host we have set on the current environment (localhost:3000). For all intents and purposes, to an API consumer it is just as if we are requesting the Todos API directly.

In reality, the Prism API Proxy is doing a bunch of processing on the traffic passing through it. It logs the traffic to the API Designer for easy debugging. In addition, when the API Discovery setting is toggled on in the environment, it uses this HTTP traffic to automatically build endpoint definitions. That's right, it inspects the query string, headers, request body, and response body, to automatically build JSON Schemas, examples, and more for your endpoints. It even makes best guesses at dynamic path params in your URL!

API Discovery currently only works in the OS X app version of the designer, with the local instance of Prism API Proxy. It does not work via the web designer, or with the hosted instance of Prism.

Here's how to get it working, step by step:

  1. In the designer, create a workspace -> project -> environment.
  2. Set the API Host in the environment settings, and make sure that an API is actually running at that location! The host should include the protocol, so something like "http://localhost:3000", not "localhost:3000".
  3. Toggle the API Discovery option to "On" in the environment proxy settings.
  4. Save the environment by clicking "Save" at the top of the screen.
  5. Select "Local Proxy" in the proxy bar dropdown (bottom left of the screen), and make sure that it is toggled to on and running.
  6. Load one of your endpoints through the local proxy. You can do this in your browser for GET requests, or send requests via the API Designer, curl, etc. For example, if you have a "GET /todos" endpoint, and the proxy is running on http://localhost:4010, visit http://localhost:4010/todos in your browser. After a moment, you will see the new endpoint in your endpoints list in the API Designer!
  7. Repeat step 6 for the rest of your endpoints.
  8. Smile.

We are incredibly excited about this feature, and would love your feedback. Try it out, and let us know what you think!

In Part II, we will explore how to use this API Discovery functionality in other ways. For example, transparently to discovery private APIs that you don't have access to, and integrating it with pre-existing test suites.

If you have not requested an invite to the StopLight beta, head on over to https://stoplight.io to get started.

Happy Designing!
The StopLight Team
Marc, Rana, Tom, and Vazha

In Part II, we explore how to map out private APIs that we have no control over.