APIs

Blackbird provides tools for developing and managing your APIs, whether you're building a new API or iterating on an existing specification. It supports OpenAPI Specifications, which are JSON or YAML documents that follow the OpenAPI standard. After you add an API specification to your Blackbird catalog, it can be used to create mock instances, generate code, and deploy to hosted, non-production environments for testing and iteration.

You can use and manage APIs in the Blackbird UI and CLI, but the functionality varies. Use the following sections to learn about the differences.

Using API specifications in the UI

The Blackbird UI provides a user-friendly interface to help you interact with API specifications in the following ways:

• Import API specifications
• Create an API specification using AI in the UI
• Upload an existing API specification in the UI
• Edit an API specification in the UI
• Remove an API specification in the UI

Import API specifications

You can import existing API specifications directly from your Git repositories, allowing you to easily integrate your version control system. For more information, see Git in Integrations.

Create an API specification using AI in the UI

You can use an AI chatbot to describe the type of API you want to create and generate a specification based on your request.

To create an API specification using AI:

1. Open the Blackbird UI.

2. In the left pane, choose APIs.

3. Choose the Add API button.

4. Choose the Create An API tile.

5. In the prompt, provide a description of the API you want to create. For example, you could provide the following description for a payment processing API:

   I want to create a new API for processing payments. Use OpenAPI 3.1.0. The service should have paths and operations related to accepting user payment requests, processing payments, and handling payment errors.

6. (Optional) After reviewing the content, provide additional prompts to refine the API specification before adding it to your API catalog. For example, you can make changes to existing paths, add new paths, or update schemas.

   Note: You can edit your API after adding it to your API catalog. For more information, see Edit an API specification.

7. When you’re ready, choose the Accept button.

8. (Optional) On the Review Specification page, update the following:

   • API Name – Provide a name for your API specification.
   • API Description – Provide a description for your API specification.
   • API tags – Add tags that you can use to identify your resources.

     Note: The Tags feature displays in the UI but isn't available, yet. We'll support tags in a future release.

   • Mock Instance – Create a simulated version of your API specification that replicates the behavior in a controlled environment for testing purposes.

     Note: For more information on mocking, see Mock instances.

9. Choose the Create API button.

Upload an existing API specification in the UI

If you already have an API specification, you can upload it directly into your API catalog.

To upload an API specification:

1. Open the Blackbird UI.

2. In the left pane, choose APIs.

3. Choose the Upload An API tile.

4. In the Upload API section, you can either drag and drop a file into the area or click it to browse and select a file.

5. (Optional) On the Review Specification page, update the following:

   • API Name – Provide a name for your API specification.
   • API Description – Provide a description for your API specification.
   • API tags – Add tags that you can use to identify your resources.

     Note: The Tags feature displays in the UI but isn't available, yet. We'll support tags in a future release.

   • Mock Instance – Create a simulated version of your API specification that replicates the behavior in a controlled environment for testing purposes.

     Note: For more information on mocking, see Mock instances.

6. Choose the Create API button.

Edit an API specification in the UI

You can modify an existing API specification as your API design evolves.

To edit an API specification:

1. Open the Blackbird UI.

2. In the left pane, choose APIs.

3. Choose the name of an API in your catalog.

4. In the API Actions pane, choose Edit API Specification. Your API specification opens in an interface where you can edit it either manually or using AI prompts.

5. In the Request Changes field, provide a description of the change you want to make. For example, you could provide the following description for a payment processing API:

   Update the /payments/process endpoint to accept an optional retry boolean field in the request body to indicate if the payment should be retried on failure.

6. (Optional) Make additional modifications to your API specification.

7. Choose Accept Changes to apply the patches, and then Save to confirm your updates.

Next steps

Create a new mock instance based on your updated API. For more information, see Mock instances.

Remove an API specification in the UI

You can remove API specifications from the catalog. When you remove an API, the API and its data are permanently deleted from your catalog. This operation deallocates the API instance, so you can create a new instance in its place.

To remove an API specification:

1. Open the Blackbird UI.
2. In the left pane, choose APIs.
3. In the tile of the API you want to remove, choose the three vertical dots to expand the menu.
4. Choose Remove.

Using API specifications in the CLI

The Blackbird CLI provides a fast and flexible way to interact with your API specs directly from the command line in the following ways:

• Add an API to the Blackbird catalog
• Update an existing API with the CLI
• View APIs with the CLI
• Delete an API specification with the CLI

Add an API to the Blackbird catalog with the CLI

You can create a new API in your Blackbird catalog by providing an API name and the path to the API specification:

For more information on your options, see API in the Blackbird CLI Reference.

Notes: If you want to import APIs from Git or create an API using AI, you must use the Blackbird UI. For more information, see Using API specifications in the UI.

Update an existing API with the CLI

You can update an API specification by providing a new API name and path to the API specification:

View APIs with the CLI

You can list API specifications in your Blackbird catalog in the following ways:

To list the details for one specification, use the following command and provide the API’s slug name:

To list the details for all API specifications, use the following command.

Delete an API specification with the CLI

You can use the CLI to remove an API specification from your Blackbird catalog.

To delete an API specification, use the following command and provide the API’s slug name:

You’ll be prompted to choose whether to delete its associated instances. If you confirm, the instances will be permanently removed from the system. If not, the instances will remain, but the API will be removed from your catalog.