Add service via URL

Appear allows you to monitor a URL and ingest the service schema from it.

In Appear, you can create a service by providing a URL to an endpoint or API service. This allows Appear to automatically detect, ingest, and generate the API schema using the introspector—without requiring an OpenAPI spec upload or network traffic detection.

How It Works

1. Create an Empty Service – Start by defining a new service in Appear.

2. Enter the Endpoint URL – Provide the URL where the API is hosted (e.g., staging, development, production).

3. Appear Introspects the API – The introspector fetches the schema from the provided endpoint.

4. Service is Generated – Appear constructs the full service definition, just as if you had uploaded an OpenAPI spec.

This UI show's an empty service page with the 'Servers' field in focus. This is where you enter the URL of the service.

Why Use a URL Instead of an Upload?

• Real-Time API Discovery – Automatically generates an API schema from a live endpoint.

• No Manual OpenAPI Spec Needed – If you don’t have an OpenAPI document, Appear builds one for you.

• Continuous Schema Updates – Appear can re-ingest the schema when changes occur at the endpoint.

Supported URL Types

• Direct API Endpoints – URLs that return a structured API response.

• Service Root URLs – Appear will attempt to infer the API structure if the service provides discoverable metadata.

• Environments & Branches – Add multiple URLs to track different versions of your API.

---

Server URL with variables in Appear

The server URL supports variables when defining a service in Appear. You can use placeholders within the URL that can be dynamically replaced based on the environment, user input, or configuration settings.

How It Works

Instead of hardcoding a static URL, you can define parts of the URL as variables using curly braces {}. These variables can then be set dynamically when making API requests or generating documentation.

For example:

servers:
  - url: https://{env}.api.example.com/v1
    variables:
      env:
        default: staging
        enum:
          - dev
          - staging
          - production

Why Use Variables?

1. Multi-Environment Support – Easily switch between development, staging, and production without redefining the entire API structure.

2. Flexible Configuration – Define API behaviors based on different user settings or deployment contexts.

3. Reusable Documentation – OpenAPI specifications and generated docs remain adaptable for various environments.

How Appear Leverages This

• When adding a service, you can define variables within the server URL.

• Appear will resolve these variables dynamically when interacting with the API.

• Documentation and introspection will reflect the available environments or configurations.

Using server variables makes your API setup more adaptable, ensuring smooth transitions between environments while keeping the documentation concise and maintainable.

---

Next Steps

• Modify or Extend the Generated Schema – After the service is generated, you can refine the service definition within the Catalog view

Adding a service from a URL is a fast, automated way to bring your API into Appear, providing instant documentation and visibility without additional setup.

---

If you have any queries or require support with the above instructions, please get in touch with us.