2 posts
line 시작하며 안녕하세요. SRE(Site Reliability Engineer)로 일하고 있는 어다희입니다. 저희 팀은 Media Platform SRE를 비롯해 글로벌 트래픽 관리 업무를 담당하고 있습니다. 그동안 ‘신뢰성 향상을 위한 SLI/SLO 도입’ 시리즈를 통해 SLI/SLO의 개념과 필요성을 살펴보고 플랫폼과 서비스에 적용한 사례를 공유해 왔습니다. 신뢰성 향상을 위한 SLI/SLO 도입 1편 - 소개와 필요성 신뢰성 향상을 위한 SLI/SLO 도입 2편 - 플랫폼 적용 사례 신뢰성 향…
toss Toss Payments treats its Open API not just as a communication tool, but as a long-term infrastructure designed to support over 200,000 merchants for decades. By focusing on resource-oriented design and developer experience, the platform ensures that its interfaces remain intuitive, consistent, and easy to maintain. This strategic approach prioritizes structural stability and clear communication over mere functionality, fostering a reliable ecosystem for both developers and businesses. ### Resource-Oriented Interface Design * The API follows a predictable path structure (e.g., `/v1/payments/{id}`) where the root indicates the version, followed by the domain and a unique identifier. * Request and response bodies utilize structured JSON with nested objects (like `card` or `cashReceipt`) to modularize data and reduce redundancy. * Consistency is maintained by reusing the same domain objects across different APIs, such as payment approval, inquiry, and cancellation, which minimizes the learning curve for external developers. * Data representation shifts from cryptic legacy codes (e.g., SC0010) to human-readable strings, supporting localization into multiple languages via the `Accept-Language` HTTP header. * Standardized error handling utilizes HTTP status codes paired with a JSON error object containing specific `code` and `message` fields, allowing developers to either display messages directly or implement custom logic. ### Asynchronous Communication via Webhooks * Webhooks are provided alongside standard APIs to handle asynchronous events where immediate responses are not possible, such as status changes in complex payment flows. * Event types are clearly categorized (e.g., `PAYMENT_STATUS_CHANGED`), and the payloads mirror the exact resource structures used in the REST APIs to simplify parsing. * The system ensures reliability by implementing an Exponential Backoff strategy for retries, preventing network congestion during recipient service outages. * A dedicated developer center allows merchants to register custom endpoints, monitor transmission history, and perform manual retries if automated attempts fail. ### External Ecosystem and Documentation Automation * Developer Experience (DX) is treated as the core metric for API quality, focusing on how quickly and efficiently a developer can integrate and operate the service. * To prevent the common issue of outdated manuals, Toss Payments uses a documentation automation system based on the OpenAPI Specification (OAS). * By utilizing libraries like `springdoc`, the platform automatically syncs the technical documentation with the actual server code, ensuring that parameters, schemas, and endpoints are always up-to-date and trustworthy. To ensure the longevity of a high-traffic Open API, organizations should prioritize automated documentation and resource-based consistency. Moving away from cryptic codes toward human-readable, localized data and providing robust asynchronous notification tools like webhooks are essential steps for building a developer-friendly infrastructure.