Publish an API to the WunderHub

In this guide, we will walk you through how to publish an API to the WunderHub. It should not take more than a few minutes to complete.

Overview#

Publishing an API to the WunderHub is useful for many reasons. At its core, sharing your API to WunderHub allows others to import it into their projects with a single command. This enables new ways of collaboration as API integrations are usually a tedious process.

You can either share an API publicly, with the whole community, or privately, with a specific Organization. In case of the latter, you can create an Organization on the WunderHub and invite your team to join it.

The process of publishing an API to the WunderHub is as follows. First, you introspect the API and transform it into the WunderGraph format. This concept is similar to Docker, that allows you to bundle applications into a portable format, just slightly different because we're applying the idea to APIs.

WunderGraph doesn't build a container for your API. Instead, we're transforming the API into a virtual Graph. This allows WunderGraph users to integrate APIs with a single command and join data from multiple APIs with ease.

Let's get started publishing our first API!

Prerequisites#

First, install wunderctl and log into the Hub.

npm i -g @wundergraph/wunderctl
wunderctl login

This will install wunderctl globally and log you in to the WunderHub.

Next, head over to the Hub and create an Organization. You need to create an Organization to publish your API to.

With that, we're ready to configure and publish our API.

Configuration & Publishing of the API#

Create an empty directory and init a new project with the "publish-api" template.

wunderctl init --template publish-api

Open up the wundergraph.config.ts file, it has lots of comments and instructions to help you get started.

If we break down the configuration file, introspecting and publishing a GraphQL API can be as simple as:

// wundergraph.config.ts

const weatherApi = introspect.graphql({
    url: "https://graphql-weather-api.herokuapp.com/",
});

configurePublishWunderGraphAPI({
    organization: "wundergraph",
    name: "weather",
    isPublic: true,
    shortDescription: "A public GraphQL Weather API",
    keywords: ["weather"],
    apis: [
        weatherApi,
    ],
});

First, introspect the API using GraphQL introspection. Then generate the configuration to publish the API.

Finally, we need to "run" this TypeScript configuration and publish our API.

wunderctl generate --publish

The wunderctl generate command will generate the configuration to the ./generated directory. Using the --publish flag will automatically publish the API to the WunderHub.

You can also omit the --publish flag and publish the API manually like so:

wunderctl publish wundergraph/weather

Conclusion#

That's it! You've published your first API to the WunderHub.

We're currently supporting REST APIs (by introspecting OpenAPI specs), GraphQL APIs, Apollo Federation and various Databases. All of them are supported and can be published and shared through the Hub.

Happy sharing!

Considerations#

One thing to note is namespacing when publishing an API to the Hub. API Namespacing is a feature that enables smooth integration of APIs, even if naming conflicts occur, as namespacing automatically solves these issues.

To facilitate namespacing, all root operation fields are being prefixed with the namespace. This means, if you're publishing a namespaced API and the user is also using namespacing, the resulting API will have double namespacing. This means, a root field could be named usernamespace_publishernamespace_rootfield.

This behaviour could be intended, but most of the time you'd want to avoid this. In most cases, you should publish your API un-namespaced, and let the user decide to namespace it, if they want.