API 세상에는 두 종류의 API 블록이 있습니다. 퍼블릿 / 프라이빗 여부는 API 노출 방식(내부망, 인터넷)으로 결정되지 않습니다. API 누구에게 제공되느냐가 관건입니다.
퍼블릭 API
서드파티가 제공할 경우 퍼블릭 API
외부에 서비스 또는 제품 형태로 제공됩니다.
프라이빗 API
API를 작성한 곳 내부에서만 사용할 경우 프라이빗 API
개발자 경험(Developer Experience)
API의 개발자 경험(Developer Experience)이란 API를 사용하는 개발자들의 경험을 의미합니다. 이는 API 사용을 위한 등록 절차와 어떻게 API를 사용하는지에 관해 설명하는 문서화와 문제에 처했을 때 해결하는 것을 돕는 기술 지원 등을 의미합니다. 그렇지만 DX라 칭해지는 주제에서 가장 공을 들여야 하는 주제인 API 디자인을 소홀히 한다면 위에 언급한 노력은 모두 의미가 없어집니다.
API의 목적은 사람들에게 이루고자 하는 바를 가급적 단순하게 이루게 해주는 데 있습니다.
사용자가 할 수 있는 일에 집중하면 인터페이스는 단순해진다.
API의 목표 식별 과정
누가 API를 사용하는가?
무엇을 할 수 있는가?
어떻게 하는가?
하기 위해서는 무엇이 필요한가?
끝나면 무엇을 반환하는가?
파라미터는 반드시 필요한 데이터만을 제공해야 하고 불필요한 정보는 제공해서는 안 됩니다. 또한, 백엔드가 자체적으로 처리할 수 있는 데이터를 포함해서도 안 됩니다.
OAS(OpenAPI Specification) : 프로그래밍 언어에 상관없이 사용하는 REST API 명세 포맷
OAS vs Swagger
직관적인 API 디자인하기
명확한 이름 정하기
사용하기 쉬운 데이터 타입과 포맷 정하기
바로 사용할 수 있는 데이터 선택하기
직관적인 상호작용
입력과 출력은 반드시 직관적이어야 한다.
모든 가능한 에러는 반드시 식별되어야 한다.
에러 피드백은 반드시 무엇이 문제인지 알려주고 가능하다면 컨슈머 스스로 해결할 수 있게 도와주어야 한다.
여러 개의 에러를 하나씩 따로 응답하는 것은 피해야 한다.
성공 피드백은 무슨 일이 벌어졌는지와 그 다음에 무엇을 해야하는지에 대한 정보를 제공해주는 것이 좋다.
4단계 일관성
1단계 - API 내부에 일관성이 존재
2단계 - 팀 API / 회사 / 조직 간의 일관성이 존재
3단계 - 도메인 간의 API의 일관성이 존재
4단계 - 외부 세계와 일관성이 존재
API는 정말 필요한 것들만 요청하고, 정말 보여줘야 하는 것들만 외부에 노출해야 합니다.
시멘틱 버저닝
메이저 숫자는 브레이킹 체인지가 발생할 때만 올라갑니다. 필수 파라미터가 추가되는 경우가 그러한 경우입니다.
마이너 숫자는 새로운 기능이 추가되고 하위 호환성이 유지되는 경우에 올라가며, HTTP 메서드나 리소스 경로가 REST API에 추가되는 경우를 예로 들 수 있습니다.
패치 숫자는 하위 호환이 가능한 버그 수정의 경우에 올라갑니다,
API의 세계에서는 시멘틱 버저닝은 단 두자리의 숫자로만 구성되어 있습니다.
브레이킹
논브레이킹
API 디자인 지침
처음엔 작고 정확하게
우베 컨셉
발전하고, 적응하고, 고쳐라
함께 만들고 도그마(Dogma)는 버리기
API 구성 및 분할해보기
기억에 남는 문장
API 디자인이란 무엇인가
웹 애플리케이션 프로그래밍 인터페이스는 우리가 살고 있는 연결된 세상의 중추라 할 수 있습니다. … API를 연결된 세상의 중추에 비유했다면, API 디자인 자체는 중추가 세워지는 토대라고 말할 수 있습니다.
-p002
API의 주된 목적은 인터페이스입니다. 인터페이스란 두 개의 시스템, 대상, 조직, 또는 그 밖의 대상들이 만나고 상호작용하는 지점을 의미합니다. 인터페이스란 API를 사용할 때 소프트웨어 내부에서 실제로 벌어지는 구체적인 구현을 의미하는 것이 아닌 추상화된 개념을 의미합니다.
-p004
API는 일반적으로 소프트웨어를 위한 것입니다. 그렇지만 소프트웨어를 만들고 사용하는 주체는 누구일까요? 바로 개발자이며 사람입니다. 사람들이 기대하는 프로그래밍 인터페이스는 유용하고 단순해야 합니다. … 인터페이스에 디자인이 중요한 이유입니다.
-p009
레스토랑 주문과 API의 상황을 비교
레스토랑 주문과 API의 상황을 비교
개발자들은 백엔드나 Go나 Java 언어로 작성된 단일 애플리케이션이건 NodeJS나 Python이나 기타 아무 언어로 작성된 API에 연계되건 백엔드에는 전혀 관심이 없습니다. … 개발자와 애플리케이션은 오직 API만 알고 있으면 됩니다. … 그렇지만 구현을 숨기는 것 만으로는 충분치 않습니다. 구현을 숨기는 것이 중요한 건 사실입니다만, API를 사용하는 사람들이 목표로 하는 것은 아닙니다.
-p012
어설픈 API 디자인의 끔찍한 결과설명서가 있어야 비로소 이해할 수 있지만 그마저도 완벽하게 이해할 수 없다
형편없이 디자인된 제품들은 잘못 쓰이거나 제대로 쓰이지 않거나 아예 쓰이지 않습니다. 이런 것들은 사용자들에게만 위험한 것이 아니라 제품을 만든 조직에도 위험합니다. … 디자인은 중요합니다. 어떤 종류의 인터페이스이건 말입니다. 따라서 API라고 예외는 없습니다. … 형편없이 디자인된 API는 이해하기도 사용하기도 끔찍하게 어려울뿐더러 끔찍한 결과를 불러올 가능성이 높습니다.
-p014 ~ p015
API를 디자인하는 방법을 학습한다는 말은 단순히 프로그래밍 인터페이스를 디자인하는 법을 배우는 것만을 의미하진 않습니다. API 디자인을 학습하기 위해서는 기술뿐 아니라 API 디자인의 모든 측면을 이해해야 합니다. API를 디자인하려면 인터페이스 자체에만 초점을 맞출 게 아니라 인터페이스를 둘러싸는 전체 맥락을 알아야 하고 모든 사용자와 소프트웨어와 관련된 사항에 공감할 수 있어야 합니다. API 디자인에 원칙이 없다면 컨텍스트에서 벗어날 가능성이 매우 큽니다. 따라서 API 디자인을 할 때는 반드시 커스터머의 측면과 프로바이더 측면으로 인터페이스의 두 가지면을 고려해야 합니다.
-p016
무언가를 디자인한다는 건, 예를 들어 원격 드론 제어 리모컨을 만든다고 치면, 리모컨을 사용할 사용자가 누구인지 그들이 이것을 사용하는 목적이 무엇일지 정확히 이해해야 합니다. … 이것들은 사용자들이 쉽게 사용할 수 있어야 하며, 가장 중요하게도 안전해야 합니다.
-p017
API를 디자인한다는 것은 여러분 혼자 이해하기 쉽고 사용하기 쉬운 인터페이스를 만드는 것을 의미하지 않습니다. 반드시 매우 안전한 인터페이스를 설계해야 합니다. 민감한 데이터나 동작을 컨슈머에게 과도하게 노출해서는 안됩니다.
-p018
사용자를 위한 API 디자인하기
우리는 서로 연관된 포괄적인 요구사항들을 정리할 수 있도록 컨슈머의 관점에 중점을 두어야 합니다. 즉, API 사용자의 관점과 API를 소비하는 컨슈머 소프트웨어의 입장으로 생각해야 합니다. 이런 관점은 API 디자인의 초석이자, API를 디자인하는 사람들에게 디자인 중에 반드시 따라야 하는 원칙입니다. 이러한 관점을 견지하기 위해서는 API 디자인의 관점을 이해해야 할 뿐 아니라, 반대로 API 디자인에 방해될 수도 있는 다른 관점에 대해서도 이해해야 합니다.
🔔견지: 어떤 견해나 입장 따위를 굳게 지니거나 지킴
-p019 ~ p020
사용하기 쉽고, 이해하기도 쉬운 API를 만드는 건 우리가 좋은 관점에 집중하고 있어야 가능합니다. 이 말은 곧 올바른 관점을 의미합니다. 사용자가 할 수 있는 일에 집중해야 합니다. 만약 소프트웨어가 어떻게 동작하는지에 집중하기 시작하면 재앙이 벌어집니다. 사용자가 무엇을 하는지에 중점을 두면 현실 세계 사물의 사례에서 봤듯이 모든 일이 부드럽게 흘러갈 겁니다.
-p024
프로그래밍 인터페이스 디자인하기
리스폰스를 디자인할 때, 수정된 리소스를 맹목적으로 매핑해서는 안됩니다. 항상 컨텍스트에 맞게 속성을 제거하거나 이름을 변경하여 데이터 구조에 맞추어야 합니다.
일관된 디자인에는 변형이나 모순이 없습니다. 일관된 디자인은 사용자의 이전 경험을 활용하여 직관적인 인터페이스를 만드는 데 도움이 됩니다. 일관성 없는 디자인은 다양성 또는 모순을 불러들여 인터페이스를 이해하고 사용하기 어렵게 만듭니다.
-p165
안전한 API 디자인하기
민감 정보를 표현하는 4가지 방법 1. 민감한 데이터이지만 필수요소가 아니라면 제거한다. 2. 민감한 정보를 제거할 수 없다면, 민감하지 않은 형태로 표현을 순화한다. 3. 조합 시 민감한 정보들을 제거한다. 4. 값을 암호화한다.
민감한 목표들을 취급한다는 것은 우리에게 이것들이 민감한 데이터를 조작하는지 또는 민감한 액션을 유발하는지 식별해 내는 것을 필요로 합니다. 각 목표에 대한 식별이 완료되면, 우리는 이것들이 정말로 필요한 것인지 판단하고, 정말로 필요한 존재라면 컨슈머의 스코프나 최종 사용자의 권한에 따라 이 목표들에 접근할 수 있도록 해주어야 합니다. 그렇지만 스코프나 권한 둘 중 하나만으로는 충분하지 않을 겁니다.
-p249
API 디자인 발전시키기
규격을 바꿔 기존 사용자들이 사용할 수 없게 만드는 변화를 브레이킹 체인지(Breaking Change)라고 합니다.
-p255
브레이칭 체인지의 원인 1. 속성의 이름을 변경 2. 속성의 위치 이동 3. 필수 속성의 제거 4. 필수 속성에서 선택 사항으로 변경 5. 속성의 타입 변경 6. 속성의 포맷 변경 7. 속성의 특징 변경 (길이, 소수자 범위, 배열 요소의 길이 확장) 8. 속성의 의미 변경 9. enum 값 추가
브레이킹 체인지 중 에러가 없어서 문제가 발생한 줄도 모르는 것을 사일런트 브레이킹 체인지(Silent Breaking Change)라고 합니다.
-p270
컨텍스트에 맞는 API 디자인하기
사람의 손을 타는 영역(예: 국제 송금 같은 특정 상황)에서는, 동기화된 리퀘스트/리스폰스 메커니즘을 사용하는 것이 제일 나은 선택이 아닐 수 있습니다. 그러므로 API를 디자인할 때 컨슈머와 프로바이더 사이의 잠재적인 한계를 모두 고려하고, 필요하다면 REST API를 벗어나는 다른 디자인도 고려해 가며 제일 나은 선택을 해야 하는 이유입니다.
-p334
SSE 명세
적절한 표현을 선택하는 것은 API 디자이너에게 익숙한 것, 마음에 드는 디자인, 유행하는 것 따위를 선택하는 것이 아닙니다. 컨텍스트를 따라 원하는 내용에 부합하는 표현을 선택해야 합니다.
-p356
API 문서화하기
API의 경우 구성 요소는 최소한 성공 및 오류 사례 모두에 대해 사용 가능한 목표와 입력 및 출력입니다. API의 문서화는 간단한 설명과 보안에 대한 정보가 포함되어야 합니다.
-p373
성장하는 API
요구사항 분석은 API만을 위한 작업이 아닙니다. 요구사항 또는 문제를 분명하게 식별하는 것은 무언가를 만들기에 앞서 반드시 해결해야 하는 것입니다.
댓글