OpenApiEndpoint Configuration

Configure OpenAPI endpoints to expose operations

OpenApiEndpoint Configuration

Defines an OpenAPI endpoint that exposes operations from a connector as a REST API endpoint.

Schema Properties

Property	Type	Required	Default	Description
ApiName	`string`	Yes	-	Name of the API this endpoint belongs to
ApiVersion	`string`	Yes	-	Version of the API
Configuration	`Dictionary<string, object>`	No	`{}`	Endpoint-specific configuration and operation parameters
Route	`string`	Yes	-	URL route for the endpoint (relative to API prefix)

YAML Examples

Basic Endpoint

apiVersion: weik.io/v1
kind: OpenApiEndpoint
metadata:
  name: get-customers
spec:
  ApiName: northwind-api
  ApiVersion: v1
  Route: /customers
  Configuration:
    OperationId: listCustomers
    Method: GET

Endpoint with Path Parameters

apiVersion: weik.io/v1
kind: OpenApiEndpoint
metadata:
  name: get-customer-by-id
spec:
  ApiName: northwind-api
  ApiVersion: v1
  Route: /customers/{customerId}
  Configuration:
    OperationId: getCustomer
    Method: GET
    Parameters:
      customerId:
        Type: path
        Required: true
        Description: Customer ID

POST Endpoint with Request Body

apiVersion: weik.io/v1
kind: OpenApiEndpoint
metadata:
  name: create-order
spec:
  ApiName: northwind-api
  ApiVersion: v1
  Route: /orders
  Configuration:
    OperationId: createOrder
    Method: POST
    RequestBody:
      Required: true
      ContentType: application/json
      Schema:
        customerId: string
        items: array
        total: number

Complete CRUD Endpoints

apiVersion: weik.io/v1
kind: OpenApiEndpoint
metadata:
  name: list-products
spec:
  ApiName: products-api
  ApiVersion: v1
  Route: /products
  Configuration:
    OperationId: listProducts
    Method: GET
    Parameters:
      limit:
        Type: query
        Required: false
        Default: 50
      offset:
        Type: query
        Required: false
        Default: 0
---
apiVersion: weik.io/v1
kind: OpenApiEndpoint
metadata:
  name: get-product
spec:
  ApiName: products-api
  ApiVersion: v1
  Route: /products/{productId}
  Configuration:
    OperationId: getProduct
    Method: GET
---
apiVersion: weik.io/v1
kind: OpenApiEndpoint
metadata:
  name: create-product
spec:
  ApiName: products-api
  ApiVersion: v1
  Route: /products
  Configuration:
    OperationId: createProduct
    Method: POST
    RequestBody:
      Required: true
      ContentType: application/json
---
apiVersion: weik.io/v1
kind: OpenApiEndpoint
metadata:
  name: update-product
spec:
  ApiName: products-api
  ApiVersion: v1
  Route: /products/{productId}
  Configuration:
    OperationId: updateProduct
    Method: PUT
---
apiVersion: weik.io/v1
kind: OpenApiEndpoint
metadata:
  name: delete-product
spec:
  ApiName: products-api
  ApiVersion: v1
  Route: /products/{productId}
  Configuration:
    OperationId: deleteProduct
    Method: DELETE

Endpoint with Response Configuration

apiVersion: weik.io/v1
kind: OpenApiEndpoint
metadata:
  name: search-customers
spec:
  ApiName: northwind-api
  ApiVersion: v1
  Route: /customers/search
  Configuration:
    OperationId: searchCustomers
    Method: POST
    RequestBody:
      Required: true
      ContentType: application/json
    Responses:
      "200":
        Description: Successful search
        ContentType: application/json
      "400":
        Description: Invalid search parameters
      "500":
        Description: Internal server error
    Caching:
      Enabled: true
      Duration: 300

Usage Notes

OpenApiEndpoint configurations map REST API routes to connector operations, creating a RESTful API interface.

Route Patterns

Routes support path parameters using curly braces:

/customers - Static route
/customers/{id} - Single parameter
/customers/{customerId}/orders/{orderId} - Multiple parameters

Routes are relative to the API prefix defined in the Api configuration. For example:

API prefix: /api/v1
Endpoint route: /customers
Full URL: /api/v1/customers

HTTP Methods

Common HTTP methods in the Configuration.Method field:

GET - Retrieve resources
POST - Create resources
PUT - Update resources (full replacement)
PATCH - Update resources (partial update)
DELETE - Delete resources

Operation Configuration

The Configuration object supports:

OperationId - Unique identifier for the operation
Method - HTTP method
Parameters - Query, path, and header parameters
RequestBody - Request body schema and requirements
Responses - Response definitions by status code
Caching - Response caching configuration
RateLimit - Operation-specific rate limiting
Authentication - Operation-level authentication requirements

Parameter Types

Parameters can be specified in different locations:

path - In the URL path (/customers/{id})
query - In the query string (/customers?limit=10)
header - In HTTP headers

Best Practices

Use RESTful route conventions
Group related endpoints under the same API
Include appropriate HTTP methods for each operation
Document parameters and request/response schemas
Use consistent naming patterns
Implement proper error responses
Consider versioning strategy for API evolution
Enable caching for read operations when appropriate
Set appropriate rate limits per operation
Test endpoints with API testing tools

API Documentation

Endpoints defined with OpenApiEndpoint automatically generate OpenAPI/Swagger documentation, accessible at the API’s documentation endpoint.