API Specification

The API Specification feature allows users to define and structure incoming requests and expected responses for their workflow APIs. This functionality simplifies accessing request values as defined variables throughout the workflow.

Request Specification

Users can define the expected request structure for the API Call.

• Click on the Trigger Menu (•••) on the REST API Call Trigger and click on Edit.

  

• Under the “Request” section you’ll see the default request structure.

• Click on the + icon to add fields to the request schema. You can also click on a field, let’s say query, to add nested fields and parameters.

  

Response Specification

Users can also define the expected response from the API.

• Click on the </> icon on the Return Node to open the Response Specification.

  

• Under the “Response” section you’ll see the default response structure.

{
  "200": {
    "title": "Success Response",
    "type": "object",
    "properties": {
      "text": {
        // added this property
        "type": "string",
        "description": "The generated text"
      }
    }
  }
}

Accessing Request Values

Users can access the request values defined in the Request Specification throughout the workflow using the Context Menu.

Example Scenario - Implementing BYOK

Let's consider implementing a Bring Your Own Key (BYOK) system within BuildShip.

We require incoming API requests to include an Authorization header containing the user's API Key. Additionally, the API needs a prompt query parameter, which will act as the User Prompt for the OpenAI Text Generator node generating a story.

To modify the Request Definition for this scenario:

• Go to the Request section in your REST API Call trigger.
• Define the Authorization header: Click on the Request Headers and use the + icon to add a nested field. Provide appropriate Label, Key, Description, and set its type to string.
• Define the prompt query parameter: Click on the Query section and add a nested field using the + icon. Provide appropriate Label, Key, Description, and set its type to string.

These defined request variables can now be easily accessed via the context menu throughout the workflow.