REST API

vNext platformu üç ana endpoint grubu sunar: Definition, Function, Instance.

Base URL örneği: http://localhost:4201 (default offset) OpenAPI versiyon: 3.0.4

Definition Endpoints

POST /api/v1/definitions/publish

Component (workflow, task, function, schema, view, extension) deploy etmek için kullanılır.

Request body: PublishInput

Field	Type	Required	Description
key	string	✓	Component anahtarı
flow	string	✓	Flow ismi
domain	string	✓	Owning domain
version	string	✓	Component versiyonu (SemVer)
flowVersion	string	✓	Flow versiyonu
tags	string[]	–	Etiketler
attributes	object	✓	Component definition payload
data	PublishDataInput[]	–	Master data publish (opsiyonel)

Response: 200 OK.

---

Function Endpoints

GET /api/v1/{domain}/functions

Belirtilen domain'de tanımlı tüm function'ları döner.

Parameter	In	Description
domain	path	Domain adı

GET /api/v1/{domain}/functions/{function}

İlgili function'ı çalıştırır (workflow bağımsız).

Parameter	In	Description
domain	path	Domain adı
function	path	Function key
version	query	Function versiyonu (opsiyonel; varsayılan: latest)

GET /api/v1/{domain}/workflows/{workflow}/instances/{instance}/functions/{function}

Function'ı instance context'inde çalıştırır.

Parameter	In	Description
domain	path	Domain adı
workflow	path	Workflow key
instance	path	Instance ID
function	path	Function key
Version	query	Function versiyonu
Extensions	query	Çalıştırılacak extension key listesi
TransitionKey	query	İlgili transition (varsa)
Role	query	Authorization rolü
FunctionKey	query	Inner function reference
QueryRoles	query	Query roles dahil edilsin mi (boolean)
If-None-Match	header	ETag (304 Not Modified için)

---

Instance Endpoints

POST /api/v1/{domain}/workflows/{workflow}/instances/start

Yeni instance başlatır.

Query parameters:

• version — workflow versiyonu (opsiyonel)
• sync — true/false (default false); bkz. Async / Sync
• extensions — extension key listesi (response'a dahil edilir)

Request body: CreateInstanceDto

Field	Type	Description
key	string	Instance key (max 100 char)
tags	string[]	Etiketler
attributes	object	Initial instance data
stage	string | null	Kullanıcı tanımlı durum bilgisi (max 120 char, serbest metin)

Responses:

• 200 OK → StartInstanceOutput (id, key, status, attributes, eTag, extensions)
• 400 Bad Request → ProblemDetails
• 404 Not Found → workflow bulunamadı
• 409 Conflict → key collision

PATCH /api/v1/{domain}/workflows/{workflow}/instances/{instance}/transitions/{transitionKey}

Bir instance üzerinde transition tetikler.

Query parameters: sync, extensions

Request body: TransitionDataInput

Field	Type	Description
key	string	Transition idempotency key
tags	string[]	Etiketler
attributes	object	Transition payload data
stage	string | null	Kullanıcı tanımlı durum bilgisi (max 120 char, serbest metin)

Responses:

• 200 OK → TransitionOutput
• 400 Bad Request, 403 Forbidden (yetki yok), 404 Not Found, 409 Conflict, 503 Service Unavailable

POST /api/v1/{domain}/workflows/{workflow}/instances/{instance}/retry

Faulted instance'ı yeniden çalıştırır.

Query parameters: sync

Request body: TransitionDataInput

Responses:

• 200 OK → RetryInstanceOutput (id, status, retriedTransitionId)
• 400, 404 → ProblemDetails

GET /api/v1/{domain}/workflows/{workflow}/instances/{instance}

Instance metadata + data döner (extension dahil).

Query parameters: extensions, version Headers: If-None-Match (ETag)

Responses:

• 200 OK → GetInstanceOutput
• 304 Not Modified → ETag eşleşti
• 404 Not Found

GET /api/v1/{domain}/workflows/{workflow}/instances

İlgili workflow'dan üretilen instance'ları filtreler ve sıralar (extension dahil değildir).

Query parameters:

• filter — JSONPath benzeri filter syntax (bkz. Instance Filtering)
• extensions — extension key listesi
• page (1-1000), pageSize (1-100), sort, orderBy, version

GET /api/v1/{domain}/workflows/{workflow}/instances/{instance}/transitions

Instance'ın transition history'sini döner.

---

Common DTOs

CreateInstanceDto

{
  key?: string;        // max 100 chars
  tags?: string[];
  attributes?: any;
  stage?: string;      // max 120 chars, kullanıcı tanımlı durum bilgisi
}

GetInstanceOutput

{
  id?: string;          // uuid
  key?: string;
  flow?: string;
  domain?: string;
  flowVersion?: string;
  eTag?: string;
  entityEtag?: string;
  tags?: string[];
  metadata?: InstanceMetadataDto;
  attributes?: any;
  extensions?: { [key: string]: any };
}

InstanceMetadataDto

{
  currentState?: string;
  effectiveState?: string;
  status?: InstanceStatus;
  effectiveStateType?: StateType;       // initial|intermediate|finish|subFlow|wizard
  effectiveStateSubType?: StateSubType; // none|success|error|terminated|suspended|busy|human|cancelled|timeout
  completedAt?: string;     // ISO datetime
  duration?: number;
  createdAt: string;
  modifiedAt?: string;
  createdBy?: string;
  createdByBehalfOf?: string;
  modifiedBy?: string;
  modifiedByBehalfOf?: string;
  stage?: string;              // max 120 chars, kullanıcı tanımlı durum bilgisi
}

StartInstanceOutput / TransitionOutput

{
  id: string;
  key?: string;
  status: InstanceStatus;
  attributes?: any;
  eTag?: string;
  entityEtag?: string;
  extensions?: { [key: string]: any };
}

RetryInstanceOutput

{
  id: string;
  status: InstanceStatus;
  retriedTransitionId: string;
}

TransitionDataInput

{
  key?: string;
  tags?: string[];
  attributes?: any;
  stage?: string;      // max 120 chars, kullanıcı tanımlı durum bilgisi
}

PublishInput

{
  key: string;          // max 100 chars, [a-zA-Z0-9-]
  flow: string;         // max 100 chars
  domain: string;       // max 50 chars, [a-zA-Z-]
  version: string;      // max 180 chars
  flowVersion: string;
  tags?: string[];
  attributes: any;
  data?: PublishDataInput[];
}

ProblemDetails (RFC 7807)

{
  type?: string;
  title?: string;
  status?: number;
  detail?: string;
  instance?: string;
}

---

ETag (Concurrent Update Control)

Instance read response'larında eTag ve entityEtag döner. Update isteği için If-None-Match (read-after) veya If-Match (update concurrency) header'ı kullanılabilir. Bkz. Core Principles → ETag.

Domain Filtreleme + URL Templates

API endpoint URL'leri Url Templates konfigürasyonu ile özelleştirilebilir (HEOTAS pattern, API gateway uyumu için).

İlgili

• Async / Sync
• Instance Filtering
• Instance Data
• API Reference Index — C# interface'ler