Public API v1 sözleşmesi

Bu sayfa kabul edilmiş API sözleşmesi ile public exposure manifestinden üretilir ve elle düzenlenmez. RPC ayrıntıları için operasyon kataloğuna, alan tanımları için public tip kataloğuna bakın.

Manifest durumu contract_projection_not_deployed; bu contract tanımı tek başına deployment kanıtı değildir.

Üretim otoritesi

Alan	Değer
Contract	munderecat-public-api-v1
Contract şema sürümü	1
Major	1
Manifest durumu	contract_projection_not_deployed
Public operasyon	20
schema	api_v1
postgrest_rpc_prefix	/rest/v1/rpc
operation_revision_suffix	_v1
permit_overloads	false
expose_storage_relations	false
source_partition	exposure_manifest.public_surface
unversioned_alias	forbidden
dispatch_major_source	profile_and_rpc_suffix
dispatch_order	major_before_operation
required_profile	api_v1
major_mismatch_error	unsupported_contract

Çağrı modeli

Her versioned RPC yolu /rest/v1/rpc/{rpc_name} biçimindedir. Mantıksal operation key client ve envelope kimliğidir; dış RPC adı ise _v1 suffix’li allowlist değeridir. Storage relation’ları public değildir, overload ve unversioned alias kabul edilmez.

Envelope’lar

Type parameter	Kural	Kaynak
operation_response_data	type_source	operations.response_type
operation_response_data	cardinality_source	operations.data_cardinality
operation_response_data	nullability_source	state_payload_contract.states
operation_response_data	public_type_closure	required

Başarılı yanıt

Alan	Tip	Required	Nullable
request_id	uuid	Evet	Hayır
operation_id	operation_key	Evet	Hayır
result_state	result_state	Evet	Hayır
state_context	api.state_context	Evet	Hayır
release_context	api.release_context	Evet	Hayır
data	operation_response_data?	Evet	Evet
page	api.page?	Evet	Evet

page alanı her başarılı yanıtta bulunur; pagination yoksa null olur.

Hatalı yanıt

Alan	Tip	Required	Nullable
request_id	uuid	Evet	Hayır
operation_id	operation_key?	Evet	Evet
error	api.error	Evet	Hayır
release_context	api.release_context?	Evet	Evet

release_context, nullable_only_before_dispatch kuralına bağlıdır.

Release context

Kural	Değer
Success’ta zorunlu	Evet
Transaction başında pin	Evet
Bağımsız release pinlerini reddet	Evet

Alan	Tip	Required	Nullable
api_deployment_id	uuid	Evet	Hayır
api_contract_release_id	uuid	Evet	Hayır
api_operation_revision_id	uuid	Evet	Hayır
code_release_id	uuid	Evet	Hayır
schema_release_id	uuid	Evet	Hayır
data_release_set_root	sha256	Evet	Hayır
policy_release_set_root	sha256	Evet	Hayır
exposure_manifest_root	sha256	Evet	Hayır

Sonuç durumları

Durum	Data	Retryable	Terminal
available	required	Hayır	Evet
empty	typed_empty	Hayır	Evet
pending	absent	Evet	Hayır
unavailable	absent	Politikaya bağlı	Evet
ambiguous	typed_visible_set	Hayır	Evet
retired	lifecycle_summary	Hayır	Evet

Durum payload union’ı

Discriminator result_state; union kapalıdır ve bilinmeyen durum contract_violation sayılır.

Durum	Data	State context	Operation binding
available	operation_cardinality	nullable_fields	Tüm uygun operasyonlar
empty	typed_zero_length_list	nullable_fields	entity_occurrences_list, repetition_members_list, alignment_targets_list, annotations_list
pending	null	retry_after_or_status_required	Tüm uygun operasyonlar
unavailable	null	reason_required	Tüm uygun operasyonlar
ambiguous	operation_ambiguity_path_minimum_two	reason_required	entity_current_resolve → data.target_entity_ids; alignment_targets_list → data
retired	operation_lifecycle_path_required	reason_required	entity_exact_get → data.lifecycle; entity_current_resolve → data.lifecycle; curation_proposal_get → data.lifecycle

state_context alanları

Alan	Tip	Required	Nullable
reason_code	string?	Evet	Evet
retry_after_ms	integer?	Evet	Evet
status_resource_id	uuid?	Evet	Evet

Invariant	Değer
pending_requires_retry_or_status_resource	true
non_retryable_forbids_retry_after	true

Hata sözleşmesi

Hata objesinin dört alanı her varyantta bulunur:

Alan	Tip	Required	Nullable
code	error_code	Evet	Hayır
retryable	boolean	Evet	Hayır
detail_code	string?	Evet	Evet
retry_after_ms	integer?	Evet	Evet

Kod	HTTP	Retryable	Public detail
invalid_request	400	Hayır	validation_code_only
unauthenticated	401	Hayır	absent
not_found_or_forbidden	404	Hayır	absent
unsupported_contract	406	Hayır	supported_major_metadata
conflict	409	Hayır	conflict_code_only
continuation_invalid	409	Hayır	absent
response_budget_exceeded	422	Hayır	operation_limit_only
rate_limited	429	Evet	retry_after_only
integrity_failure	503	Hayır	incident_id_only
service_unavailable	503	Evet	retry_after_only
timeout	504	Evet	retry_after_only

Koda bağlı detail_code ve retry_after_ms kısıtları kapalı discriminator varyantlarında listelenir. Dispatch öncesi ve sonrası operation_id / release_context ilişkisi failure envelope varyantlarında gösterilir.

Client state projection

Kural	Değer
Loading	local_request_only_not_server_state
Terminal yanıt loading’i durdurur	Evet

Result state eşlemesi

API	Client
available	content
empty	empty
pending	pending
unavailable	unavailable
ambiguous	ambiguous
retired	retired

Error eşlemesi

API	Client
invalid_request	error
unauthenticated	signed_out
not_found_or_forbidden	not_found
unsupported_contract	update_required
conflict	conflict
continuation_invalid	refresh_required
response_budget_exceeded	unavailable
rate_limited	retrying
integrity_failure	unavailable
service_unavailable	unavailable
timeout	retrying

Yetkilendirme profilleri

Profil	Roller	Çalışma	DB kontrolleri	Red hatası
public_release_read	anon, app_runtime, authenticated	security_invoker	release_visibility	not_found_or_forbidden
curation_read	authenticated	security_invoker	trusted_subject, current_curation_eligibility, current_revocation_state	not_found_or_forbidden
curation_write	authenticated	reviewed_security_definer	trusted_subject, current_curation_eligibility, current_revocation_state, current_authority_epoch, current_freeze_epoch, exact_policy_release	not_found_or_forbidden

Pagination

Alan	Değer
Strateji	opaque_authenticated_cursor
Yön	forward_only
Varsayılan sayfa	50
Azami sayfa	100
Cursor TTL	900 saniye
Kimlik doğrulama	hmac_sha256_rotatable_server_key
Toplam sayı	omitted
Deterministik tiebreaker	operation_declared_stable_uuid

Cursor alanları: cursor_schema_version, api_deployment_id, api_contract_release_id, api_operation_revision_id, data_release_set_root, policy_release_set_root, query_shape_sha256, authorization_subject_sha256, visibility_scope_sha256, order_key, page_size, expires_at.

Cursor rejection nedenleri: expired, signature_mismatch, operation_mismatch, deployment_mismatch, contract_mismatch, release_mismatch, policy_mismatch, query_shape_mismatch, principal_mismatch, visibility_mismatch, page_size_escalation.

Yanıt bütçeleri

Kural	Değer
measurement_scope	complete_operation_response
over_budget_behavior	fail_before_response_serialization
partial_response	forbidden
error	response_budget_exceeded
chapter_reconstruction	all_or_nothing

Profil	DB statement	Item	Byte	P95 ms	Timeout ms
point_read	8	1	262144	100	1000
chapter_read	12	50000	16777216	350	2500
bounded_list	8	100	524288	150	1500
graph_list	12	100	1048576	250	2000
curation_write	20	1	262144	500	3000

Curation submission

Kural	Değer
canonicalization_profile	curation-proposal-json-v1
freeze_point	before_insert
persist_behavior	insert_exact_immutable_revision
change_behavior	submit_successor_with_parent_binding
review_binding	proposal_revision_id_and_payload_root

Zorunlu commitment’lar: proposal_payload_root, action_inventory_root, target_inventory_root, evidence_inventory_root, expected_state_root, authority_snapshot_root, policy_root.

Compatibility sınıflaması

Değişiklik	Sınıflama
operation_added	additive_optional_contract_behavior
optional_response_field_added	additive_optional_contract_behavior
required_field_added	required_public_contract_behavior_removed_or_reinterpreted
field_removed	required_public_contract_behavior_removed_or_reinterpreted
field_type_or_cardinality_changed	required_public_contract_behavior_removed_or_reinterpreted
result_or_error_meaning_changed	required_public_contract_behavior_removed_or_reinterpreted
authorization_weakened	authorization_or_disclosure_weakened_incompatibly
supported_tuple_removed_without_boundary	supported_release_tuple_invalidated_without_successor_or_major_boundary

Makine çıktıları

Contract kaynak sınıfları: accepted_api_contract, exposure_manifest.public_surface, accepted_openapi_projection.

Çıktı sınıfları: openapi_v1, typescript_api_types_v1, typescript_operation_client_v1.

Zorunlu generator header alanları: generator_id, generator_version, api_contract_root, exposure_manifest_root, openapi_root.

Politika	Değer
manual_edit_behavior	reject
private_type_behavior	reject
drift_behavior	release_blocker
type_dependency_closure	exact_transitive_public_surface
unconstrained_json_behavior	reject
result_union	closed_discriminated_union
error_union	closed_discriminated_union
typescript_exhaustiveness_check	required_never
unknown_variant_behavior	release_blocker

Repo artifact’ları packages/contracts/generated/openapi-v1.json, packages/contracts/generated/api-v1.ts ve packages/contracts/generated/client-v1.ts dosyalarıdır.

Bunlar dokümantasyonun girdisi değildir; contract ve exposure manifestinin aynı doğrulanmış üretiminden çıkan makine arayüzleridir.