API Portal Quickstart

In this quickstart we will integrate the Speakeasy SDK into a locally running API in order to begin building an API developer experience portal.

info

Requirements:

• A Github account
• Access to the Speakeasy beta program

Step 1: Fork API Template Repo

If you don't have an API you can run locally on-hand, don't sweat it! We have a template repository with an API written in Go which you can use to follow along.

Head to the template repository and click:

Name the repo speakeasy-quickstart, select private and create the repository:

Now git clone into the created repository:

git clone https://github.com/YOUR_USERNAME/speakeasy-quickstart.git

Open up the repository in the code editor of your choice, and keep it to the side while we create your Speakeasy account.

Step 2: Create your Workspace

To create your account head over to https://app.speakeasyapi.dev and authenticate with a GitHub profile.

Enter in a name for your Workspace, and click "Create Workspace".

Step 3: Generate an API Key

From the dashboard home page, select 'Add an API'. You will be taken to a wizard that will help you get started with setting up an API key to use in the SDK.

(Optional) Upload an OpenAPI schema: For the sake of simplicity, we will skip this step.

tip

If you were setting up Speakeasy for your production APIs, we strongly recommend starting with your OpenAPI schema.

Give your API a name and version: Enter an API name ("api id") and version number. These will be used to identify your API in the platform.

• Api ID: this can be any string up to 128 characters, using Alphanumeric characters or the following symbols (. - _ ~). For example: test-api
• Version ID: this can be any string up to 128 characters, using Alphanumeric characters or the following symbols (. - _ ~). For example: v1.0.0

Generate a new Speakeasy API key: Click "generate API key". Notice that the code block on the page will update with the API ID, version and API key.

Add the Speakeasy SDK to your API: For now, just copy the code block somewhere you can reference later.

Wrap Up: Click submit.

Now we'll head back to the code editor.

Step 4: Integrate the Speakeasy SDK

info

This quickstart uses the Go SDK, but if you have an API in another language that you would like to test with, please checkout the language-specic instructions for installing the SDK.

In your code editor you should see a directory structure as follows:

Configure the Speakeasy SDK

First, we're going to configure the Speakeasy SDK to use the API Key we created in Step 3. Open up cmd/server/main.go

At the top of the file you will see a list of imported packages. Add the speakeasy SDK to the list:

"github.com/speakeasy-api/speakeasy-go-sdk"

Next, head to line 36 within the appStart() function. Just below the initialization of the API's DB, we are going to configure the Speakeasy SDK. Add the following code, with your API key added:

// Connect to the postgres DB
db, err := initDatabase(ctx, cfg, a)
if err != nil {
  return nil, err
}

//Configure the Speakeasy SDK
speakeasy.Configure(speakeasy.Config{
  APIKey:    "YOUR_API_KEY",
  ApiID:     "test-api",
  VersionID: "v1.0.0",
})

Save the file, the SDK is now configured. Next we need to make sure the API's router is using Speakeasy's middleware.

Use The Middleware

Open up internal/core/listeners/http/http.go in your code editor, and jump down to line 49 within the New() function which instantiates the server. You will see a block of code where the router is being created and configured to use middlewares. Add the Speakeasy middleware to this list:

r := mux.NewRouter()
r.Use(tracingMiddleware)
r.Use(logTracingMiddleware)
r.Use(requestLoggingMiddleware)
r.Use(speakeasy.Middleware)

Save the file, and your done integrating the Speakeasy SDK! Now we'll get it deployed, so you can start seeing request logs flow into the platform.

Step 5: Deploy Your API Locally

The template repo you're working off of has a docker file that makes deploying easy.

tip

If you don't already have Docker, you'll need to install it.

Open Docker Desktop and then run the following command while in the root folder of the speakeasy-quickstart project:

DOCKER_BUILDKIT=1 COMPOSE_DOCKER_CLI_BUILD=1 docker-compose build --no-cache

you should now have the template API runinng on localhost port: 8080!

Step 6: Send Sample Request logs To Your API with Postman

To make testing easy, the template repo contains a Postman collection. This has mocked data you can send to the API.

tip

If you don't already have Postman, you can install it here.

Within Postman import the collection from the speakeasy-quickstart repo:

Click on the BootstrapUsers collection and add host and port variables to the table with values: localhost and 8080.

Then right click on the BootstrapUsers collection and run the collection:

Step 7: See Request logs Populate In The Platform

Navigate back to https://app.speakeasyapi.dev - you should see live requests reflected in the Requests tab of the dashboard.

Step 8: Create a customer facing Developer Experience Portal

With Speakeasy now capturing request logs from your API we can put together Developer Experience Portal for developers who will be using your API. Go to the Portal page and fill in the following fields to host a portal at a subdomain of Speakeasy {your-company}.portal.speakeasyapi.dev. In the near future we will support custom domain hosting.

Fill in:

• Subdomain: the subdomain name you want to access your portal at. For this quickstart we will use demo.
• Title: the Portal name you want your API users to see. Lets add "Demo"
• Login Call Back URL: this is the URL that Speakeasy will redirect users to confirm authenticated login. Often this is your own app's existing login page. This enables Speakeasy to work with your existing authentication provider. For this demo you can use Speakeasy itself, https://app.speakeasyapi.dev. See our integration guide for more details.
• Docs Link: Link to API documentation if you have any. For this demo you can use Speakeasy itself: https://speakeasyapi.dev.
• Primary Color: Hex value for a secondary DevEx portal color, for example: #FFCC4D.
• Secondary Color: Hex value for a secondary DevEx portal color, for example: #F897F4.
• Enable Pages: Only selected pages will be enabled in the DevEx portal. Enabling pages that do not require authentication (e.g. client sdks) will change login-redirect behavior to prompt the user instead of being automatic.

Hit save and access the portal at the subdomain you specified: demo.portal.speakeasyapi.dev

That's it! You've successfully set up the Speakeasy SDK with a live API and a DevEx portal for your customer to use. Head over to the integration guides to take advantage of all the features the platform has to offer.