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:

{
  "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

{
  "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

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

Required Fields

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

Enums

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

Arrays

{
  "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:

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

3. Be Specific with Validation

Use appropriate validation rules:

{
  "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:

{
  "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:

{
  "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 - Learn about workflow services with a complete example
• Data Manipulation - Working with data in workflows
• Describe your API - API documentation for managed services
• 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