---
url: /services/workflow/api-generation.md
description: >-
  Define a JSON Schema on a workflow Start Event to auto-generate OpenAPI docs,
  validate inputs, and type the workflow service API.
---

# Automatic API Generation

Workflow services automatically generate their API based on the input schema you define. This makes it easy to create well-documented, validated services without manually writing API specifications.

## How It Works

When you define an input schema on the **Start Event** in your workflow, the platform uses this schema to:

1. **Generate API Documentation**: Creates OpenAPI/Swagger documentation automatically
2. **Validate Requests**: Ensures incoming requests match your expected structure
3. **Provide Type Information**: Gives consumers clear information about required and optional fields
4. **Enable Better Testing**: The Service Jobs page uses the schema for input validation

## Defining the Input Schema

To define your workflow's API, you need to specify a JSON Schema on the Start Event:

### Step-by-Step

1. **Select the Start Event** in your workflow (the circle ○ at the beginning)
2. **Open the Properties Panel** on the right side
3. **Navigate to "API Description"** section
4. **Paste your JSON Schema** in the `Request Schema` field

### Example Schema

Here's a simple example for a workflow that processes flight routes:

```json
{
  "type": "object",
  "properties": {
    "flightRoutes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "origin": { "type": "string" },
          "destination": { "type": "string" }
        },
        "required": ["origin", "destination"]
      }
    },
    "mapOutput": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "ref": {
          "type": "string",
          "enum": ["datapool"]
        }
      },
      "required": ["id", "ref"],
      "additionalProperties": false
    }
  },
  "required": ["flightRoutes", "mapOutput"]
}
```

This schema defines:

* **flightRoutes**: An array of route objects, each with origin and destination (both required)
* **mapOutput**: An object with datapool reference information (id and ref both required)
* Both top-level properties are marked as required

## Benefits of Schema-Based API Generation

### 1. **Automatic Validation**

When you execute your workflow through the Service Jobs page, the platform validates your input against the schema:

* Missing required fields are caught before execution
* Type mismatches are detected early
* Invalid enum values are rejected

### 2. **Clear Documentation**

The schema serves as documentation for service consumers:

* Clear indication of required vs. optional fields
* Type information for all properties
* Validation rules (formats, enums, patterns)
* Nested object structures

### 3. **Better Developer Experience**

Developers using your service get:

* IDE autocompletion (when schema is available)
* Clear error messages when validation fails
* Examples of valid request formats

### 4. **Version Control**

The schema is part of your workflow definition:

* Changes are tracked along with your workflow
* Easy to see API changes over time
* Rollback capabilities if needed

## JSON Schema Features

You can use standard JSON Schema features to define your API:

### Types

```json
{
  "type": "string"     // Text values
  "type": "number"     // Numeric values
  "type": "integer"    // Whole numbers only
  "type": "boolean"    // true/false
  "type": "array"      // Lists of items
  "type": "object"     // Nested structures
}
```

### Validation Rules

```json
{
  "type": "string",
  "minLength": 3,
  "maxLength": 50,
  "pattern": "^[A-Z]{3}$",  // Airport codes: JFK, LAX, etc.
  "format": "uuid"          // Predefined formats
}
```

### Required Fields

```json
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name"]  // age is optional
}
```

### Enums

```json
{
  "type": "string",
  "enum": ["datapool", "local", "external"]
}
```

### Arrays

```json
{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "origin": { "type": "string" },
      "destination": { "type": "string" }
    }
  },
  "minItems": 1,
  "maxItems": 100
}
```

## Best Practices

### 1. **Use Descriptive Property Names**

Choose clear, self-explanatory names:

✅ `flightRoutes`, `destinationAirport`, `departureTime`
❌ `data`, `input1`, `x`

### 2. **Add Descriptions**

While not shown in the basic example, you can add descriptions:

```json
{
  "type": "object",
  "properties": {
    "flightRoutes": {
      "type": "array",
      "description": "List of flight routes to optimize",
      "items": { ... }
    }
  }
}
```

### 3. **Be Specific with Validation**

Use appropriate validation rules:

```json
{
  "type": "string",
  "format": "uuid",           // For IDs
  "pattern": "^[A-Z]{3}$"     // For airport codes
}
```

### 4. **Mark Fields as Required Appropriately**

Only mark fields as required if they're truly necessary:

```json
{
  "required": ["flightRoutes"],  // Must have routes
  // mapOutput might be optional if results can be returned directly
}
```

### 5. **Use additionalProperties Wisely**

Control whether extra fields are allowed:

```json
{
  "type": "object",
  "properties": { ... },
  "additionalProperties": false  // Reject unknown fields
}
```

## Testing Your Schema

After defining your schema:

1. **Save** your workflow
2. **Deploy** to make the schema active
3. **Run Service** from the Service Jobs page
4. The platform will validate your input against the schema
5. Fix any validation errors that appear

## Accessing the Generated API

Once deployed, your workflow service has:

* **API Endpoint**: Available through the platform
* **OpenAPI Specification**: Auto-generated from your schema
* **Validation**: Automatic request validation
* **Documentation**: Available to service consumers

## Related Topics

* [Introduction & Tutorial](/services/workflow/air-traffic-tutorial) - Learn about workflow services with a complete example
* [Data Manipulation](/services/workflow/data-manipulation) - Working with data in workflows
* [Describe your API](/services/managed/openapi) - API documentation for managed services
* [Service Configuration](/services/managed/service-configuration) - General service configuration

## Next Steps

Now that you understand API generation:

1. Define a schema for your workflow's start event
2. Test the validation with sample inputs
3. Share your service with clear API documentation
4. Iterate based on consumer feedback