WEB / WEB-17.01

API contracts, endpoints ve REST

Bir endpoint URL’den fazlasıdır: method, representation, status ve operation semantics birlikte contract oluşturur. REST’in architecture sınırını JSON API alışkanlığından ayır.

CORE · RED · BLUE · ARTIFACT · PRACTICE

Hareket olmadan bütün senaryoları oku

GET JSON

Contract seç
Client GET /api/notes/tea ve Accept: application/json seçimini hazırladı. Bu public read niyetidir; endpoint henüz request almadı ve client’ta response yoktur.
Duru / Client
GET /api/notes/tea; Accept: application/json hazır
API endpoint
No request
Resource owner
No selection
Client contract
No validation
Request ulaştı
Endpoint method/target ve Accept’i aldı; resource selection ve representation policy henüz bitmedi.
Duru / Client
Waiting response
API endpoint
GET /api/notes/tea received
Resource owner
No selection
Client contract
No validation
Resource seç
Logical note sabit public resource owner’dan seçilir; resource bir JSON byte string’iyle aynı şey değildir.
Duru / Client
Waiting response
API endpoint
GET /api/notes/tea received
Resource owner
Selected public tea note
Client contract
No validation
Media ve status
Server public note için 200 application/json body’sini hazırladı: id=tea, title=Tea note ve links array. JSON representation 80 UTF-8 octet’tir; client henüz almadı.
Duru / Client
Waiting response
API endpoint
200 JSON ready
Resource owner
Selected public tea note
Client contract
No validation
Response ulaştı
Client selected response’u şimdi aldı; prepared representation ile received representation aynı zaman değildir.
Duru / Client
200 JSON received
API endpoint
200 JSON ready
Resource owner
Selected public tea note
Client contract
No validation
Contract kontrolü
Client aldığı JSON body’yi yerel olarak parse eder ve id/title string, links array koşullarını kontrol eder. Seçilen normal body bu shape’e uyar; HTTP 200 tek başına bu sonucu veya resource iznini kanıtlamaz.
Duru / Client
200 JSON received
API endpoint
200 JSON ready
Resource owner
Selected public tea note
Client contract
id/title strings; links array

HEAD metadata

Contract seç
Client HEAD /api/notes/tea ve Accept: application/json seçimini hazırladı. Bu public read niyetidir; endpoint henüz request almadı ve client’ta response yoktur.
Duru / Client
HEAD /api/notes/tea; Accept: application/json hazır
API endpoint
No request
Resource owner
No selection
Client contract
No validation
Request ulaştı
Endpoint method/target ve Accept’i aldı; resource selection ve representation policy henüz bitmedi.
Duru / Client
Waiting response
API endpoint
HEAD /api/notes/tea received
Resource owner
No selection
Client contract
No validation
Resource seç
Logical note sabit public resource owner’dan seçilir; resource bir JSON byte string’iyle aynı şey değildir.
Duru / Client
Waiting response
API endpoint
HEAD /api/notes/tea received
Resource owner
Selected public tea note
Client contract
No validation
Media ve status
Server HEAD için 200 ve Content-Length: 80 metadata’sını hazırladı; response content’i yoktur. Uzunluk aynı JSON GET representation’ına aittir, client henüz almadı.
Duru / Client
Waiting response
API endpoint
200 HEAD ready
Resource owner
Selected public tea note
Client contract
No validation
Response ulaştı
Client selected response’u şimdi aldı; prepared representation ile received representation aynı zaman değildir.
Duru / Client
200 HEAD; 0 content
API endpoint
200 HEAD ready
Resource owner
Selected public tea note
Client contract
No validation
Contract kontrolü
Client HEAD metadata’sını değerlendirir: Content-Length: 80 ile content octet sayısı 0 farklıdır. Body olmadığı için JSON parse edilmez; bu sonuç note’un boş olduğunu göstermez.
Duru / Client
200 HEAD; 0 content
API endpoint
200 HEAD ready
Resource owner
Selected public tea note
Client contract
Metadata only; no JSON parse

Media refusal

Contract seç
Client GET /api/notes/tea ve Accept: image/png seçimini hazırladı. Bu public read niyetidir; endpoint henüz request almadı ve client’ta response yoktur.
Duru / Client
GET /api/notes/tea; Accept: image/png hazır
API endpoint
No request
Resource owner
No selection
Client contract
No validation
Request ulaştı
Endpoint method/target ve Accept’i aldı; resource selection ve representation policy henüz bitmedi.
Duru / Client
Waiting response
API endpoint
GET /api/notes/tea received
Resource owner
No selection
Client contract
No validation
Resource seç
Logical note sabit public resource owner’dan seçilir; resource bir JSON byte string’iyle aynı şey değildir.
Duru / Client
Waiting response
API endpoint
GET /api/notes/tea received
Resource owner
Selected public tea note
Client contract
No validation
Media ve status
Accept: image/png bu profilin JSON/plain media kümesine uymaz. Server bu örnekte 406 ret response’u hazırlar; HTTP bütün media uyuşmazlıklarında bu seçimi zorunlu kılmaz.
Duru / Client
Waiting response
API endpoint
406 ready
Resource owner
Selected public tea note
Client contract
No validation
Response ulaştı
Client selected response’u şimdi aldı; prepared representation ile received representation aynı zaman değildir.
Duru / Client
406 received
API endpoint
406 ready
Resource owner
Selected public tea note
Client contract
No validation
Contract kontrolü
Client aldığı 406’yı bu contract’ın beklenen media reddi olarak yorumlar. Normal note JSON shape’i doğrulanmış sayılmaz; method desteği, media seçimi ve resource izni ayrı sorulardır.
Duru / Client
406 received
API endpoint
406 ready
Resource owner
Selected public tea note
Client contract
Expected media refusal

Follow note link

Entry seç
Client documented entry target /api’yi bilir; note resource target’ı response relation’dan seçilecektir.
Duru / Client
GET /api hazır; note target bilinmiyor
API endpoint
No request
Resource owner
Public note ready
Client contract
No relation
Entry request
Endpoint public entry GET’ini aldı ve known note relation’ını içeren representation’ı hazırlayabilir.
Duru / Client
Waiting entry
API endpoint
GET /api received
Resource owner
Public note ready
Client contract
No relation
Relation üret
Server rel=note href=/api/notes/tea representation’ını local olarak hazırlar; client henüz bunu almadı.
Duru / Client
Waiting entry
API endpoint
Entry links ready
Resource owner
Public note ready
Client contract
No relation
Entry ulaştı
Client entry representation’ı aldı; href’i yalnız documented note relation semantics’i ile yorumlar.
Duru / Client
Entry links received
API endpoint
Entry links ready
Resource owner
Public note ready
Client contract
No relation
Relation seç
Client entry’deki rel=note ilişkisini yerel olarak seçti ve href=/api/notes/tea ile sonraki GET request’ini hazırladı. Henüz endpoint bu ikinci request’i almadı; başka target veya privileged action seçilmez.
Duru / Client
Entry alındı; GET /api/notes/tea hazır
API endpoint
Entry links ready
Resource owner
Public note ready
Client contract
note → /api/notes/tea
Linked request
Endpoint entry’deki href’le eşleşen benign GET target’ı aldı; independent request önceki server session context’i istemez.
Duru / Client
Entry links received
API endpoint
GET linked note received
Resource owner
Public note ready
Client contract
note → /api/notes/tea
Note response
Server public note representation’ını hazırlar; iki read interaction bütün REST constraints’ini kanıtlamaz.
Duru / Client
Entry links received
API endpoint
200 note ready
Resource owner
Public note ready
Client contract
note → /api/notes/tea
Note ulaştı
Client linked note response’unu aldı; ledger target equality’yi gösterir, complete REST conformity iddiası taşımaz.
Duru / Client
200 linked note received
API endpoint
200 note ready
Resource owner
Public note ready
Client contract
note → /api/notes/tea

ROLLER · STATE · VERİ AKIŞI

API bir interaction contract’ıdır

API bir component’in diğer component’e sunduğu operation/data contract’ını anlatır; her API web üzerinden çalışmaz. Web API bu interaction’ı web protocol üzerinden erişilebilir kılar. Atlas GET /api/notes/tea endpoint’i method ve target’ın birlikte seçtiği read operation’dır. URL’nin sonuna api yazmak veya response’u JSON yapmak kendiliğinden contract’ın tamamını açıklamaz. İzin verilen method’lar, headers, representation shape ve error anlamları da okunmalıdır.

Resource tea note’unun logical kimliğidir; representation ise o resource hakkında aktarılan bytes ve metadata’dır. Aynı resource application/json veya text/plain ile ifade edilir. Contract JSON için id ve title string’leri ile links array’ini tanımlar; plain için Tea note text’ini verir. Client HTTP status, Content-Type ve expected shape’i ayrı kontrol eder. 200 ve parse edilebilir JSON, yanlış field type’larını doğru yapmaz. Bir endpoint database table veya disk file’ın doğrudan adresi olmak zorunda değildir.

GET bu public resource’un representation’ını okur; HEAD selected metadata’yı content taşımadan verir. POST bu read-only endpoint’te 405 ve Allow: GET, HEAD üretir. GET’in safe semantics’i request’in state change talep etmemesidir; logging gibi incidental işler olabilir. Safe/idempotent classification object authorization kontrolünü yerine getirmez. Fixture’de identity yoktur ve public catalog okunur. Write API’de operation sonucu ile persistence outcome ayrıca tanımlanmalıdır.

REST constraints, representation ve hypermedia

REST Fielding’in tanımladığı architecture style’dır: client-server, stateless interaction, cache constraints, uniform interface ve layered system birlikte düşünülür; code-on-demand optional’dır. Uniform interface resource identification, representation ile manipulation, self-descriptive messages ve hypermedia’nın application state’i yönlendirmesini kapsar. Yalnız JSON ve CRUD benzerliği bu constraints’in hepsini karşıladığını göstermez.

Stateless interaction’da her request’i anlamak için gerekli context o request’te bulunur; önceki interaction’ın server’da tutulan client session context’ine bağımlılık kurulmaz. Bu server’ın resource data’sı, database’i veya cache’i olamaz demek değildir. Server-side session kullanan yaygın JSON API’ler çalışabilir; fakat bu özellik REST’in strict stateless constraint’iyle aynı değildir. HTTP protocol’un stateless semantics’i ile bir uygulamanın session design’ını ayrı değerlendir.

Örnekte entry representation /api, rel=note ve href=/api/notes/tea link’ini döndürür; client bu documented relation’ı okuyup public target’a GET yapar. Link’i kullanarak ilerlemek hypermedia fikrini somutlaştırır; bu tek küçük örnek bütün API’nin REST conformity’sini kanıtlamaz. Accept: text/plain alternate representation seçer. Fixture image/png için 406 seçer; HTTP origin’in bütün negotiation uyuşmazlıklarında zorunlu olarak 406 vermesi gerekmez. Status, body shape ve supported-media contract birlikte okunur.

Hareket olmadan bütün senaryoları oku

Shape uyuşmaz

API consumer contract’ı okundu
public tea note contract’ı id:string, title:string ve links:array ister. JSON olarak okunabilme ile consumer’ın beklediği shape’e uyum farklı koşullardır.
API contract kaydı
Contract: id string
Contract gate incelemesi
Candidate incelenmedi
Consumer sınırı
Consumer kabul etmedi
Aday representation seçildi
invalidCandidate içinde id=7, title=Tea note ve links=[] vardır. Bu yalnız değerlendirme için verilmiş candidate’tır; endpoint’in bu body’yi gönderdiği kayıtlı değildir.
API contract kaydı
Candidate: id=7
Contract gate incelemesi
Served=false
Consumer sınırı
Consumer bekliyor
Parser sonucu authority olmadı
parseable=true, JSON syntax’ın okunabildiğini gösterir. id alanı number olduğu için string isteyen contract henüz sağlanmış değildir.
API contract kaydı
Parseable=true
Contract gate incelemesi
id type: number
Consumer sınırı
Shape sonucu bekliyor
Shape gate’inde uyuşmazlık bulundu
schemaValid=false bilinen contract uyuşmazlığıdır. HTTP status veya application/json etiketi id alanının türünü düzeltmez.
API contract kaydı
Parseable=true
Contract gate incelemesi
Schema valid=false
Consumer sınırı
Accepted representation değil
Gerçek response iddiası kurulmadı
servedByNativeEndpoint=false sınırı korunur. Bu candidate’ı canlı endpoint hatası veya kaydedilmiş malformed response olarak raporlamak kanıtı genişletir.
API contract kaydı
Candidate known
Contract gate incelemesi
Contract mismatch known
Consumer sınırı
Endpoint incident kanıtı yok
Contract ve permission ayrı bırakıldı
Shape doğrulaması consumer veri beklentisini sınırlar; resource permission sağlamaz. Burada public not contract’ı incelenir, başka objelere erişim yetkisi verilmez.
API contract kaydı
Shape gate gerekli
Contract gate incelemesi
Permission ayrı soru
Consumer sınırı
Consumer acceptance withheld

Method sınırı

Endpoint method listesi okundu
/api/notes/tea yalnız GET ve HEAD tanımlar. Resource path’inin varlığı, bütün HTTP method’larının o target’ta desteklendiğini göstermez.
API contract kaydı
Allowed: GET, HEAD
Contract gate incelemesi
Method kararı bekliyor
Consumer sınırı
Permission bilinmez
Method mismatch kaydı seçildi
methodMismatch row’u POST için status=405 ve Allow=GET, HEAD bildirir. İnceleme bu fixed karar kaydını okur; yeni request göndermez.
API contract kaydı
Method: POST
Contract gate incelemesi
Expected: 405
Consumer sınırı
Permission bilinmez
Method desteği ret nedeni oldu
405 target’ın bu method’u desteklemediğini açıklar. Actor için başarılı authentication veya object authorization sonucu bu kayıtta yoktur.
API contract kaydı
POST unsupported
Contract gate incelemesi
Allow: GET, HEAD
Consumer sınırı
No authority conclusion
Allow alanı grant olarak okunmadı
Allow=GET, HEAD, desteklenen method’ları açıklar. Actor’ın bu method’larla her resource’ı okuyabileceği veya application policy’den geçtiği anlamına gelmez.
API contract kaydı
Method capabilities
Contract gate incelemesi
Allow ≠ permission
Consumer sınırı
Resource policy ayrı
Media negotiation farklı karar sayıldı
image/png isteyen negotiation kaydının status’u 406’dır. Bu örneğin ret politikasıdır; her server’ın aynı Accept koşulunda zorunlu olarak 406 vermesi beklenmez.
API contract kaydı
Method: 405
Contract gate incelemesi
Selected negotiation: 406
Consumer sınırı
Ret nedenleri farklı
Response kararının kapsamı korundu
Method desteği, representation seçimi ve permission farklı gate’lerdir. Tek bir status alanı diğer iki katmanın geçtiğini veya başarısız olduğunu kanıtlamaz.
API contract kaydı
Method gate bilinir
Contract gate incelemesi
Representation policy ayrı
Consumer sınırı
Permission sonucu yok

VARSAYIM · SINIR · KONTROL

Contract ile observed result’i karşılaştır

Controlled public endpoint’in contract’ını method/target, selected media type, status ve schema üzerinden oku. /api/notes/tea için JSON id alanının number olması parse success’e rağmen contract uyuşmazlığıdır. Bu supplied benign candidate’ı client predicate’i değerlendirir; production server’dan bozuk protocol veya saldırı response’u üretilmez. Olası etki yanlış application branch’i veya typed client’ın result’i kullanamamasıdır. Kontrol, transport success ile application contract validation’ı ayrı tutmaktır.

405 GET,HEAD policy’sini anlatır; permission granted anlamı taşımaz. 404 de absent logical resource ile deliberate concealment arasında tek başına ayrım sağlamaz. Public fixture’de bu auth soruları devreye girmez. Contract incelemesinin sınırı açıkça yazılırsa “endpoint cevap verdi, dolayısıyla bütün operation doğru” şeklindeki aşırı yorum engellenir. Response content ve metadata’nın hangi resource/representation’a ait olduğunu ilişkilendirmek gerekir.

REST etiketi ve state bağımlılığı

REST adı verilmiş bir JSON API’yi incelerken “resource URL var mı” sorusu yeterli değildir. Request’in anlamı önceki client interaction’ına bağlı server context gerektiriyorsa strict stateless constraint değerlendirmesi farklıdır. Bu durum tek başına bir vulnerability veya kullanılamaz ürün değildir; architecture iddiası ile actual behavior arasındaki farktır. Domain data’nın database’de bulunması aynı session dependency anlamına gelmez.

Hypermedia’da relation semantics ve representation contract’ı client’in sonraki transition’ı anlamasını sağlar. Yalnız href alanı görmek complete HATEOAS architecture kanıtı sayılmaz; consumer’ın onu nasıl yorumladığı gerekir. Bu derski entry-follow case yalnız documented note relation’ını kullanır. Arbitrary target, external link veya privileged operation denenmez. Defansif kontrol, desteklenen relation ile allowed read operation arasındaki bağın açık olmasıdır.

Hareket olmadan bütün senaryoları oku

HEAD byte kanıtı

GET representation kaydı seçildi
Normal JSON body’nin contentOctets değeri 80’dir. Aynı public resource’ın text/plain representation’ı Tea note metniyle 8 byte’tır; byte sayısı representation’a bağlıdır.
HTTP observation
JSON: 80 bytes
Bağlam karşılaştırması
Plain: 8 bytes
İnceleme sonucu
HEAD incelenmedi
HEAD observation kaydı okundu
HEAD kaydı status=200, declaredLength=80 ve contentOctets=0 içerir. Metadata ile bu response’da taşınan content miktarı ayrı alanlardır.
HTTP observation
HEAD status=200
Bağlam karşılaştırması
Declared length=80
İnceleme sonucu
Content octets=0
Zero content boş resource sayılmadı
HEAD response content taşımadığı için contentOctets=0’dır. Bu sıfır, GET representation’ının boş olduğunu veya storage record’unun bulunmadığını göstermez.
HTTP observation
HEAD: no content
Bağlam karşılaştırması
GET representation: 80
İnceleme sonucu
Empty resource çıkarımı yok
Karşılaştırma tuple’ı tamamlandı
Method, media type, status, declared length ve gerçek content sayısı birlikte okunur. Farklı media type’ların 80 ve 8 byte sonuçları aynı body’nin çelişkili ölçümü değildir.
HTTP observation
Method/media bağı gerekli
Bağlam karşılaştırması
Metadata ≠ content
İnceleme sonucu
Farklı representation
Database sonucu varsayılmadı
restBoundary databaseExecuted=false bildirir. HTTP byte kaydı için bir database query veya kalıcı write gerçekleştiği sonucu eklenmez.
HTTP observation
HTTP ölçümleri bilinir
Bağlam karşılaştırması
Database executed=false
İnceleme sonucu
Storage claim yok
İnceleme sonucu representation’a bağlandı
Bu kayıt HEAD semantiği ve byte ayrımını açıklar. Content delivery, DOM render veya başka media negotiation koşulları için ayrıca gözlem gerekir.
HTTP observation
HEAD content=0
Bağlam karşılaştırması
GET JSON length=80
İnceleme sonucu
Render sonucu bilinmez

Link relation

Entry representation incelendi
/api entry kaydı rel=note ve href=/api/notes/tea link’ini içerir. Bu ilişki bir sonraki documented target’ı seçmek için representation verisidir.
HTTP observation
Entry: /api
Bağlam karşılaştırması
rel=note
İnceleme sonucu
Next target bekliyor
Relation seçimi kayda bağlandı
followedRelation=note kaydı entry link’iyle eşleşir. İnceleme bu normal ilişkiyi okur; başka URL veya actor permission üretmez.
HTTP observation
Followed relation=note
Bağlam karşılaştırması
href=/api/notes/tea
İnceleme sonucu
Permission grant yok
Next target eşleştirildi
nextTarget=/api/notes/tea, seçilen href ile aynıdır. Bu belgeli geçiş, bir link ilişkisinden target seçimini gösterir; gerçek request receipt veya DOM sonucu değildir.
HTTP observation
Relation match known
Bağlam karşılaştırması
Next target match known
İnceleme sonucu
Receipt gözlemi yok
REST kapsamı ayrı değerlendirildi
completeRestConformanceClaim=false’tur. Tek bir link ve target eşleşmesi bütün REST constraint’lerinin uygulandığını kanıtlamaz.
HTTP observation
Link transition known
Bağlam karşılaştırması
Complete REST claim=false
İnceleme sonucu
Constraint review gerekli
Stateless ile resource state ayrıldı
serverResourceStateAllowed=true ve storedPreviousClientSessionContextUsed=false farklı soruları cevaplar. REST statelessness, server’da hiçbir resource verisi tutulmaması demek değildir.
HTTP observation
Resource state allowed
Bağlam karşılaştırması
Previous client context not used
İnceleme sonucu
State türleri ayrı
Eksik observation temiz sonuç olmadı
Selector’ın sıfır eşleşmesi yalnız verilen observation setini anlatır. Field veya kayıt eksikse contract doğruluğu, REST uyumu veya runtime temizliği sonucu çıkarılamaz.
HTTP observation
Observation set sınırlı
Bağlam karşılaştırması
Missing evidence ≠ clean
İnceleme sonucu
Ek gözlem gerekli

UYGULAMA · GÜVENLİK KONTROLÜ · DOĞRULAMA

Contract ledger ve independent predicates

Artifact contract method’ları GET/HEAD, resource target’ı /api/notes/tea, supported media types’ı JSON/plain ve required JSON fields’ı id/title/links olarak kaydeder. Normal record status=200, media=application/json, schemaValid=true olur. Client predicate id/title string ve links array koşullarını ayrı hesaplar. Benign id=7 candidate’ı rejected olur; bu record yalnız local schema observation’dır, gerçek gateway log schema’sı değildir.

GET plain body Tea note sekiz UTF-8 octet’tir; HEAD JSON selected representation length’ini bildirse de content 0’dır. POST’in 405 ve Allow header’ı operation support için doğrulanır; unsupported image/png 406 fixture policy’sidir. Negotiation örneği yalnız absent/JSON/plain/image-png input set’ini seçer; bütün Accept quality/wildcard parsing’i uygulanmış sayılmaz. Cache behavior veya identity decision bu ledger’in scope’u değildir.

Schema selector ve hypermedia kanıtı

XPath count(/audit/response[@status="200" and @media="application/json" and @schema="invalid"]) successful HTTP response’un invalid application shape ile eşleştiği authored observation’ları sayar. Normal valid fixture 0, supplied positive fixture 1 verir. 406 veya expected 405 bu schema condition’ına girmez; onlar ayrı contract branch’leridir. Observation yoksa count 0 clean behavior kanıtı değildir; yeterli response ve validation verisi yoktur.

Entry document’in note relation’ından alınan href ile next request target’ın eşitliğini göster. Bu, hard-coded URL varsayımından daha somut bir link-follow kanıtıdır; yine de complete architecture değerlendirmesi değildir. HTTP method semantics, media contract ve error policy değişirse client transition’ı da yeniden düşünülmelidir. Her step’te server’ın hazırladığı representation ile client’in gerçekten aldığı representation’ı ayırmak response result’in ownership’ini korur.

Operation ve representation sözleşmesini uygula

Server desteklediği method ve media type’ları dispatch kararına bağlar; yalnız dokümana yazmak yetmez. Bu read contract’ında GET ve HEAD, business mutation başlatmaz; POST seçilen operation’a girmez. Safe method, herkesin her kaynağı okuyabileceği anlamına gelmez: private kaynağa geçildiğinde identity ve permission kararı ayrıca gerekir. JSON response’un Content-Type’ı gerçek serialization ile uyuşmalı, client ise id/title/links tiplerini kullanmadan önce doğrulamalıdır.

id=7 gibi yanlış shape’i alan client, status=200 diye onu normal note view model’ine dönüştürmez; anlaşılır contract hatası gösterir. Normal JSON ve plain branch’larını, desteklenmeyen method ve media branch’larından ayrı doğrula. Link-follow akışında yalnız belgelenen relation ve beklenen API kapsamı kullanılır; bulunan her href yeni bir trusted endpoint değildir. Response veya validation kaydı eksikse ne schema doğruluğu ne access kontrolü kanıtlanmıştır.

ŞİMDİ VAKAYA UYGULA

Parse, method desteği veya link ilişkisi hangi sonucu kanıtlamaz?

Public tea note contract’ında shape, HTTP method, media type ve relation farklı alanlardır. İnceleme candidate verisini gerçek response’dan ve byte metadata’sını delivery’den ayırır.

Vakadaki API contract’ı ile browser’ın okuyabildiği representation’ı ayrı incele. Envelope, data, error ve resource permission için hangi gözlemin yeterli olduğunu tartış.

Bağlı vaka dosyasını aç ↗

ÖRNEĞİ BİRLİKTE OKUYALIM

Public note API contract ve relation ledger

Bir alan seç; hangi sonucu desteklediğini ve nerede yetersiz kaldığını incele.

Ham kaydı ve alan açıklamalarını oku

{
  "contract": {
    "resource": "public tea note",
    "target": "/api/notes/tea",
    "allowedMethods": [
      "GET",
      "HEAD"
    ],
    "supportedMediaTypes": [
      "application/json",
      "text/plain"
    ],
    "requiredShape": {
      "id": "string",
      "title": "string",
      "links": "array"
    },
    "selectionScope": [
      "absent Accept",
      "application/json",
      "text/plain",
      "image/png"
    ],
    "fullAcceptParser": false
  },
  "normal": {
    "method": "GET",
    "status": 200,
    "contentType": "application/json",
    "representation": {
      "id": "tea",
      "title": "Tea note",
      "links": [
        {
          "rel": "self",
          "href": "/api/notes/tea"
        }
      ]
    },
    "body": "{\"id\":\"tea\",\"title\":\"Tea note\",\"links\":[{\"rel\":\"self\",\"href\":\"/api/notes/tea\"}]}",
    "contentOctets": 80,
    "schemaValid": true
  },
  "plain": {
    "body": "Tea note",
    "contentOctets": 8,
    "status": 200
  },
  "head": {
    "declaredLength": 80,
    "contentOctets": 0,
    "status": 200
  },
  "methodMismatch": {
    "method": "POST",
    "status": 405,
    "allow": "GET, HEAD"
  },
  "negotiation": {
    "accept": "image/png",
    "status": 406,
    "policy": "selected fixture refusal; not mandatory universal behavior"
  },
  "invalidCandidate": {
    "representation": {
      "id": 7,
      "title": "Tea note",
      "links": []
    },
    "parseable": true,
    "schemaValid": false,
    "servedByNativeEndpoint": false
  },
  "hypermedia": {
    "entryTarget": "/api",
    "entryRepresentation": {
      "links": [
        {
          "rel": "note",
          "href": "/api/notes/tea"
        }
      ]
    },
    "followedRelation": "note",
    "nextTarget": "/api/notes/tea",
    "completeRestConformanceClaim": false
  },
  "restBoundary": {
    "serverResourceStateAllowed": true,
    "storedPreviousClientSessionContextUsed": false,
    "databaseExecuted": false,
    "codeOnDemand": "optional architectural constraint; not executed"
  },
  "selector": {
    "language": "XPath",
    "xml": "<audit><response status=\"200\" media=\"application/json\" schema=\"valid\"/></audit>",
    "xpath": "count(/audit/response[@status=\"200\" and @media=\"application/json\" and @schema=\"invalid\"])",
    "expected": 0,
    "positiveFixtureXml": "<audit><response status=\"200\" media=\"application/json\" schema=\"invalid\"/></audit>",
    "positiveExpected": 1,
    "scope": "Only authored protocol-decision observations, not product log field names or a live HTTP capture.",
    "missingFieldBehavior": "Missing observation is insufficient evidence; zero matches is not proof of correct runtime behavior."
  }
}

contract: Method/target/media/schema ve supported operation’ın birlikte tanımı.
invalidCandidate: Benign supplied local schema counterexample; wire response değil.
hypermedia: Entry relation’dan seçilen target; full REST conformity iddiası yok.

Read-only public fixture; JSON shape predicate ve limited media selection. Write/identity/complete REST/cache veya general Accept parser doğrulaması değildir.

İki yanlış kanı

JSON ve CRUD endpoint’leri varsa API otomatik REST’tir.

REST architecture constraints ve uniform interface/hypermedia anlamı ayrıca gerekir; JSON bir representation seçeneğidir.

REST stateless ise server’da database veya resource state tutulamaz.

Constraint önceki client interaction context’ine bağımlı request’i dışlar; resource data ve database ayrı state kategorileridir.

SIRA SENDE

Bu hikâyeyi sen çöz.

Sonucu tahmin et, kanıtın sınırını bul ve nedenini kendi cümlenle anlat.

JSON adayında id=7; title string ve links array. Parse edilebilmesi schemaValid için yeterli mi?

Hayır. schemaValid=false; aday sunulmaz.
Evet. Geçerli JSON bütün API sözleşmelerine uyar.

Gerekçeli cevabı oku

Hayır. schemaValid=false; aday sunulmaz. — JSON syntax ile field type kontrolü farklı aşamalardır. Number olan id, sözleşmenin istediği string değildir.

Entry representation içindeki rel:note link’inin takip edilmesi neyi öğretir?

Dersten seçilen artifact alanları; öğretim örneği

hypermedia: {"entryTarget":"/api","entryRepresentation":{"links":[{"rel":"note","href":"/api/notes/tea"}]},"followedRelation":"note","nextTarget":"/api/notes/tea","completeRestConformanceClaim":false}

JSON endpoint ve link, bütün sistemi RESTful olarak kanıtlar.
Client sonraki target’ı keşfeder; tam REST uyumu kanıtlanmaz.

Gerekçeli cevabı oku

Client sonraki target’ı keşfeder; tam REST uyumu kanıtlanmaz. — followedRelation=note ve nextTarget açıkça verilmiştir. Örnek bütün architecture constraint’lerini ölçmez.

REST stateless constraint neden server resource state’inin veya database’in yasak olduğu anlamına gelmez?

Gerekçeli cevabı oku

Server resource state tutabilir. Stateless constraint, bir request’i yorumlamak için server’da saklanan önceki client session context’ine ihtiyaç duyulmamasını ister. Client gerekli context’i request’te taşımalıdır. Bu örnekte database çalıştırılmaz; stateless kavramından storage’sız architecture veya her GET’in public olduğu sonucu çıkarılmaz.

□ Resource state ile session context’i ayırdım.

□ Stateless olmayı erişim izni saymadım.

Uygulama konsolunu aç · request / response / browser

Request, URL, cookie ve DOM örneklerini ayrıca aç

Kaynaklar ve kapsam

Roy Fielding — Dissertation Chapter 5: REST5.1.2 Client-Server · 5.1.3 Stateless · 5.1.4 Cache · 5.1.5 Uniform Interface · 5.1.6 Layered System · 5.1.7 Code-On-Demand · 5.2.1.1 Resources and Resource Identifiers · 5.2.1.2 Representations · 5.2.2 Connectors
RFC 9110 — HTTP Semantics3.1 Resources · 3.2 Representations · 8.3 Content-Type · 8.6 Content-Length · 9.2.1 Safe Methods · 9.2.2 Idempotent Methods · 9.3.1 GET · 9.3.2 HEAD · 12.5.1 Accept · 15.5.5 404 Not Found · 15.5.6 405 Method Not Allowed · 15.5.7 406 Not Acceptable
Node.js v24.13.0 — HTTP APIhttp.createServer([options][, requestListener]) · response.end([data[, encoding]][, callback]) · response.writableEnded · response.writableFinished

KENDİ NOTUN / BU TARAYICIDA

API contracts, endpoints ve REST

1. Core · Mekanizma

GET JSON

HEAD metadata

Media refusal

Follow note link

API bir interaction contract’ıdır

REST constraints, representation ve hypermedia

2. Red · Güven ve etki

Shape uyuşmaz

Method sınırı

Contract ile observed result’i karşılaştır

REST etiketi ve state bağımlılığı

3. Blue · Güvenli geliştirme ve savunma

HEAD byte kanıtı

Link relation

Contract ledger ve independent predicates

Schema selector ve hypermedia kanıtı

Operation ve representation sözleşmesini uygula

Parse, method desteği veya link ilişkisi hangi sonucu kanıtlamaz?

İki yanlış kanı

JSON adayında id=7; title string ve links array. Parse edilebilmesi schemaValid için yeterli mi?

Entry representation içindeki rel:note link’inin takip edilmesi neyi öğretir?

REST stateless constraint neden server resource state’inin veya database’in yasak olduğu anlamına gelmez?

Kaynaklar ve kapsam