2nd/10_Wiki/Topics/Architecture/API_Fundamentals.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-api-fundamentals	API Fundamentals	10_Wiki/Topics	verified	self	API basics REST GraphQL gRPC Web API	none	A	0.9	applied	api rest graphql grpc fundamentals		2026-05-10	pending	language framework typescript REST/GraphQL/gRPC/tRPC

API Fundamentals

매 한 줄

"매 contract between systems — verbs, nouns, errors, evolution". 매 RPC (1980s, Sun RPC) → CORBA (1991) → SOAP (1998) → REST (Fielding 2000) → gRPC (2015) → GraphQL (2015) → tRPC (2020). 매 2026 modern stack 은 typed end-to-end (tRPC, GraphQL Codegen, gRPC + buf) + AsyncAPI 2.x for events.

매 핵심

매 four styles

• REST: resource-oriented, HTTP verbs, stateless, cacheable. 매 public API standard.
• GraphQL: client-specified queries, single endpoint, strong types. 매 BFF / mobile.
• gRPC: binary (protobuf), HTTP/2, streaming, codegen. 매 internal, low-latency.
• tRPC: TypeScript-first, no codegen, type inference. 매 Next.js / monorepo.

매 cross-cutting concerns

• Versioning: URI (/v1), header (Accept-Version), or evolution (additive only).
• Idempotency: idempotency key for unsafe verbs (POST). At-least-once → exactly-once at API.
• Pagination: cursor (preferred) vs offset. 매 cursor 의 stable ordering.
• Errors: RFC 7807 problem+json, gRPC status codes, GraphQL errors[].
• Auth: OAuth2 / OIDC / mTLS / API key.

매 응용

1. Public REST + GraphQL — Stripe (REST), GitHub (both), Shopify (GraphQL).
2. Internal gRPC mesh — Google, Uber, Square.
3. Full-stack tRPC — Vercel, Cal.com, T3 stack.

💻 패턴

REST resource design

GET    /orders?status=pending&cursor=abc123  → 200 [{...}], next_cursor
POST   /orders                                → 201 {id, ...}, Location
GET    /orders/{id}                           → 200 {...} | 404
PATCH  /orders/{id}  (JSON Merge Patch)       → 200 {...}
DELETE /orders/{id}                           → 204

REST idempotency

app.post("/orders", async (req, res) => {
  const idemKey = req.header("Idempotency-Key");
  const cached = await redis.get(`idem:${idemKey}`);
  if (cached) return res.status(200).json(JSON.parse(cached));

  const order = await createOrder(req.body);
  await redis.setex(`idem:${idemKey}`, 86400, JSON.stringify(order));
  res.status(201).json(order);
});

Cursor pagination

const limit = 50;
const rows = await db.query(
  `SELECT * FROM orders WHERE (created_at, id) < ($1, $2)
   ORDER BY created_at DESC, id DESC LIMIT $3`,
  [cursor.ts, cursor.id, limit + 1]
);
const hasMore = rows.length > limit;
const items = rows.slice(0, limit);
const nextCursor = hasMore ? encode(items.at(-1)) : null;

GraphQL schema + resolver

type Query {
  order(id: ID!): Order
  orders(first: Int!, after: String): OrderConnection!
}
type Order { id: ID!, status: OrderStatus!, items: [Item!]! }
type OrderConnection {
  edges: [OrderEdge!]!
  pageInfo: PageInfo!
}

const resolvers = {
  Query: {
    order: (_, {id}, ctx) => ctx.dataloaders.order.load(id),
    orders: async (_, {first, after}, ctx) => paginateOrders(first, after, ctx),
  },
  Order: {
    items: (order, _, ctx) => ctx.dataloaders.itemsByOrder.load(order.id),
  },
};

gRPC service (proto3)

syntax = "proto3";
package orders.v1;

service OrderService {
  rpc Get(GetRequest) returns (Order);
  rpc List(ListRequest) returns (stream Order);  // server streaming
  rpc Watch(WatchRequest) returns (stream OrderEvent);  // bidi-friendly
}
message Order {
  string id = 1;
  OrderStatus status = 2;
  google.protobuf.Timestamp created_at = 3;
}

tRPC procedure

import { router, publicProcedure } from "./trpc";
import { z } from "zod";

export const orderRouter = router({
  get: publicProcedure
    .input(z.object({ id: z.string() }))
    .query(({ input, ctx }) => ctx.db.order.findUnique({ where: { id: input.id } })),

  create: publicProcedure
    .input(z.object({ items: z.array(z.string()).min(1) }))
    .mutation(({ input, ctx }) => ctx.db.order.create({ data: { items: input.items } })),
});
// Client gets full type inference: trpc.order.get.useQuery({id}) typed

RFC 7807 error

{
  "type": "https://api.example.com/errors/insufficient-funds",
  "title": "Insufficient funds",
  "status": 402,
  "detail": "Account 12345 has balance $5, requested $50",
  "instance": "/orders/abc"
}

매 결정 기준

상황	Style
Public 3rd-party API	REST + OpenAPI 3.1
Mobile/web with diverse query needs	GraphQL
Internal microservices, low latency	gRPC
TypeScript monorepo (Next.js)	tRPC
Real-time bidirectional streams	gRPC streaming or WebSocket
Async events	AsyncAPI + Kafka/NATS

기본값: 매 REST + OpenAPI 의 public, 매 gRPC 의 internal, 매 tRPC 의 TS monorepo.

🔗 Graph

• 부모: Distributed Systems · Web Architecture
• 변형: REST · GraphQL · gRPC · tRPC · WebSocket
• 응용: OpenAPI · API Gateway · Service Mesh
• Adjacent: OAuth2 · JSON Schema · Protocol Buffers

🤖 LLM 활용

언제: 매 cross-system contract 의 design, 매 client/server 매 separated, 매 versioned interface 필요. 언제 X: 매 internal function call (just call it), 매 single process, 매 < 100 lines glue script.

❌ 안티패턴

• GET with side effects: 매 cache poisoning, 매 idempotency violation.
• HTTP 200 with {error: ...} body: 매 status code semantics 의 ignore.
• Versioning by minor change: 매 v1/v2/v3 explosion. 매 additive evolution 의 prefer.
• Chatty API: 매 N+1 client roundtrips. 매 batch endpoint or GraphQL.
• No pagination: 매 unbounded list → OOM at scale.

🧪 검증 / 중복

• Verified (RFC 7231 HTTP, RFC 7807 problem+json, gRPC docs, GraphQL spec, tRPC docs).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — full content (REST/GraphQL/gRPC/tRPC fundamentals)