API 설계란?

API 설계는 소프트웨어 구성 요소 간의 상호 작용을 정의하고 문서화하는 프로세스입니다. 여기에는 다양한 엔드포인트 정의, 사용할 모든 형식 지정, API를 구성하는 모든 소프트웨어의 동작 정의가 포함됩니다. 특히 설계된 API는 시스템이 서로 상호 작용하는 방식과 어떤 종류의 상호 작용이 성공적인지에 대해 특별한 의미가 있습니다. 

API 선택이 다자간 의사 소통을 용이하게 하고 명확성과 효율성이 소프트웨어 복잡성을 결정할 수 있다고 결론 내리는 것은 피상적입니다. 사람들은 종종 API 설계에 여러 반복이 포함된다는 것을 깨닫지 못하는데, 특히 민감한 데이터를 처리하는 경우에 더욱 그렇습니다. 이를 위해서는 시스템이 내구성과 보호성을 갖도록 많은 테스트가 필요합니다.

따라서 API는 접근성, 구조, 사용된 프로토콜에 따라 분류됩니다. 다음은 이러한 API 유형과 특성에 대한 세부 정보입니다. 

• 가용성: API는 공개(이 경우 모든 사람이 이러한 API를 사용할 수 있음) 또는 비공개(제한된 수의 사용자 또는 조직에서 사용할 수 있음)일 수 있습니다.
• 아키텍처: API는 실제로 RESTful일 수 있으며, 종종 HTTP와 더불어 SOAP(오래된 XML 기반 프로토콜)를 사용합니다.   
• 프로토콜: API는 또한 기본 프로토콜에 따라 분류될 수 있으며, 웹 API는 인터넷을 통해 이루어지고 새롭게 도입된 GraphQL은 다른 것들 중에서 데이터 쿼리에 최적화되어 있습니다.

API를 설계할 때 RESTful 설계 원칙, 적절한 HTTP 메서드 선택, API 버전 관리, 데이터 캐싱과 같은 특정 표준과 모범 사례를 준수합니다. 이러한 조치는 액세스, 안정성, API 확장성과 같은 측면에 영향을 미칠 수 있으며, 향상된 유용성 달성을 목표로 합니다. 

HTTP 동사를 적절하고 정확하게 사용하면 특정 리소스에서 완료해야 하는 작업을 설명하는 데 더 효율적입니다. 버전 제어는 변경 사항을 적용하는 동안 기존 통합과의 호환성을 유지하는 데 중요합니다.

원활한 개발 프로세스를 원한다면 API를 만드는 데 사용할 올바른 도구를 선택하는 것은 가장 중요한 측면 중 하나입니다. Stoplight, SwaggerHub, Apigee와 같은 인기 플랫폼의 기능과 한계를 이해하면 최상의 옵션을 선택하기 위한 정보에 입각한 의사 결정이 용이해집니다. 

• Stoplight: Stoplight의 시각적 편집기는 API 사양의 생성과 반복을 용이하게 하여 팀 워크플로에 영향을 미칩니다. 이 기능에는 라이브 시나리오와 관련된 에뮬레이션에 대한 모의 및 협업적 측면을 참조하여 함께 작동하는 기능이 포함되어 있습니다. Stoplight의 API 문서화 도구는 정확하고 최신의 참조를 유지하는 데 사용될 수 있습니다. 
• SwaggerHub: 이는 API 문서화 및 협업을 위해 설계된 플랫폼입니다. 템플릿을 사용하여 사용자는 문서화 스타일과 형식을 수정할 수 있으며, 이는 사용성과 정보 밀도에 영향을 미칠 수 있습니다. SwaggerHub의 버전 제어 기능은 이에 따라 API 개발 사이클에 연결됩니다. 이 플랫폼의 협업 기능은 사용자 간 또는 특정 팀 간의 상호 작용과 정보 공유를 확장, 지원 또는 촉진할 수 있습니다.
• Apigee: Apigee는 특히 API 관리 따라서 제공하는 기능의 양에도 불구하고 API는 규모가 작거나 API 설계에 비교적 경험이 부족한 팀이 구현하는 데 더 많은 단계가 필요할 만큼 복잡할 수도 있습니다. 일부 조직의 경우 Apigee 비용으로 인해 예산을 철저히 평가해야 할 수 있습니다. 

API 버전 관리란 시간이 지남에 따라 API 내에서 변경 사항을 관리하는 것입니다. 이는 이전 버전을 삭제하지 않고 책의 새로운 판을 출시하는 것과 비슷합니다. 이는 API가 호환성을 유지하고 API를 사용하는 모든 애플리케이션이 새로운 기능, 수정 사항 또는 API의 완전한 개편을 포함하더라도 계속 실행할 수 있도록 하는 데 중요합니다.

다음은 일반적인 API 버전 관리 전략입니다.

• URI 버전 관리: URL에 설정됩니다. (예: /v1/users, /v2/users). 이해하기 쉽지만 여러 URL이 가능할 수 있습니다.
• 헤더 버전 관리: 버전은 요청 헤더에 전송됩니다(예: API-Version: v2). 이렇게 하면 URL이 깔끔해지지만 헤더는 클라이언트의 손에 맡겨집니다.
• 쿼리 매개변수 버전 관리: 쿼리 문자열로 URL에 추가된 인수가 됩니다(예: /users?version=2). 중간 정도보다 구현하기는 쉽지만, 항상 명확한 것은 아닙니다.
• 콘텐츠 협상: 클라이언트는 Accept 헤더를 사용하여 응답 형식의 필요한 버전을 나타냅니다. 이는 유연하지만 고정된 것에 비해 구현하기가 약간 더 어렵습니다.