Walkthrough

Navigate to Listings > APIs and click on the Register New API button on the top right-hand corner.

You can also access it directly here.

The first step is to provide a name for your API and upload an icon.

The name should be unique and descriptive. It will be displayed on the Sulu Hub and help users identify your API. It will also be used for search results.

The icon will be displayed on the Sulu Hub and API pages. It can be a very important part of your API’s identity.

The next step is to upload your OpenAPI specification file.

OpenAPI is a specification for building APIs. It describes the endpoints, request/response formats, and other details of your API in a human and machine-readable format.

It is used by Sulu to generate documentation and to configure your API in our infrastructure. It can also be used by developers to generate client libraries and other tools. AI agents can also parse your OpenAPI spec and make calls to your API autonomously.

To learn more about OpenAPI, visit the OpenAPI Initiative.

To start writing your OpenAPI spec, you can use the Swagger Editor.

You can upload the file directly or provide a URL to the file. We accept both YAML and JSON formats.

Things to include in your OpenAPI Spec

• OpenAPI version: 3.0.x or 3.1.x
• Info: Title, Description, Version, Contact, License, Terms of Service.
• Servers: The base URL of your API
• Paths: The endpoints of your API
• Components [optional]: Schemas, Parameters, Responses, Request Bodies, Headers.

Things to avoid in your OpenAPI Spec

• External Component References: External references are not supported by Sulu.
• Security Schemes: Sulu Hub uses its own security scheme to authenticate your API in our proxy layer. You do not need to include security schemes in your OpenAPI spec. Security schemes in your OpenAPI spec will be ignored.

How to make it as useful as possible

• Descriptions: Provide detailed descriptions for each endpoint, parameter, and response.
• Examples: Provide examples for each endpoint, parameter, and response.
• Defaults: Provide default values for parameters. This will help users try the API straight from the documentation.

The next step is to review the information you have provided so far. A lot of this information is extracted from the OpenAPI spec provided, but can be edited here. This information will be displayed on the Sulu Hub.

• Sulu Hostname Prefix: This is the subdomain you choose to access your API through Sulu Hub.

• Base URL Suffix: This is the base URL of your API on the Sulu Hub. It is generated from the server URL in your OpenAPI spec. If the path suffix does not look right, we recommend going back to the OpenAPI spec and updating the server URL to avoid confusion, but it can also be edited here.

• API Version: The version of your API. This is extracted from the OpenAPI spec, but can be edited here.

• Short Description: A brief description of your API that is displayed in the API’s card on search results. It should be short and snappy, and give users a quick idea of what your API does. By default, it is the first sentence in the description field of your OpenAPI spec, but can be edited here.

• Long Description: A longer description of your API that is displayed on the API’s page. We recommend up to 3 sentences. For more detailed information, you can use the README. By default, it is the description field of your OpenAPI spec, but can be edited here.

• Terms of Service: A link to the terms of service of your API. This is displayed on the API’s page.

• Website URL: A link to the website of your API. This is displayed on the API’s page.

• Health Check URL: A URL that Sulu will ping periodically to check if your API is up.

• README: A README.md file for your API. This is displayed on the API’s page. It can be written in Markdown and will support all the standard Markdown features. Use this to provide detailed information about your API, including how to use it, examples, features, limitations, and anything else you think is important.

The next step is to set the pricing for your API endpoints.

At the moment, we only support fixed pricing per call. We are working hard to implement more flexible pricing models, including dynamic pricing, volume discounts, and item-based pricing.

For now, you can set a price per call for each endpoint in your API.

To do this easily, we recommend using the Bulk modify feature.

The next step is to configure the gateway for your API.

The gateway is the entry point for your API on the Sulu Hub. It is responsible for routing requests to the correct endpoint, authenticating users, and enforcing rate limits.

You can configure the gateway to use the default settings, or you can customize it to suit your needs.

The gateway configuration includes:

• Upstream Hostname: The original hostname of your API. For example, if your API is hosted at api.example.com, the upstream hostname is api.example.com.
• Upstream Protocol: The protocol used by your API. It can be HTTP or HTTPS.
• Upstream Port: The port used by your API. It can be any valid port number. The default port for HTTP is 80, and the default port for HTTPS is 443.
• Request Size Limit: The maximum size of a request that the gateway will accept.
• Proxy Timeout: The maximum time the gateway will wait for a response from your API. When this time is exceeded, the gateway will return a 504 error to the client.

Secrets

If your API requires secrets, such as API keys or tokens, you can add them here. This is specially useful to authenticate your API in the gateway layer. Every time a user makes a request to your API through the Sulu Hub, the gateway will add these secrets to the request. This allows your backend to authenticate the requests coming from our gateway.

We support both header and query secrets. They can be added in their respective sections.

We automatically generate a X-Suluhub-Secret header that contains a secret token unique to your API. This token can be used to authenticate requests coming from the Sulu Hub, but its use is optional.

The final step is to review all the information you have provided and submit your API.

Here you can review how you API will look on the Sulu Hub.

You can also decide whether to publish it as Listed or Unlisted. Unlisted APIs are not visible on the Sulu Hub, but can still be accessed by users with the URL. This is useful for testing or private APIs.

We recommend that you first publish your API as Unlisted to test it and make sure everything is working as expected. Once you are happy with it, you can change it to Listed to make it visible to the public.