API 설계

편집기를 사용하여 API를 설계합니다.

요구 사항에서 API로

대부분의 기술과 마찬가지로 API는 문제에 대한 해결책입니다. 올바른 API를 설계하려면 다음 질문에 답하여 해결하려는 문제가 명확하게 정의되어 있는지 확인해야 합니다.

예를 들어, 음식 배달 회사인 경우 파트너 네트워크가 배달 서비스를 제공하는 레스토랑 데이터베이스를 찾아보고 검색할 수 있도록 하는 API를 구축할 수 있습니다.

이 예에서 API는 회사의 파트너를 대상으로 합니다. 파트너는 레스토랑에 대한 데이터를 조작하고 특정 필터링 및 정렬 기능을 사용하여 데이터에 대한 검색 쿼리를 수행해야 합니다.

또 다른 예: 캘린더 SaaS 회사인 경우 전 세계의 다른 프런트엔드 개발자가 캘린더 시스템을 기반으로 새로운 모바일 및 웹 응용 프로그램을 만들 수 있도록 API를 구축할 수 있습니다.

API 소비자에 대해 생각하는 것은 소비자에게 좋은 개발자 경험을 제공하기 위한 첫 번째 단계입니다. 이는 API를 돋보이게 하고 참여도를 높이는 데 도움이 됩니다.

API를 설계할 때 사용되는 네 가지 주요 개념이 있습니다.

리소스는 소비자가 API를 통해 상호 작용할 요소입니다. 리소스는 경로로 고유하게 식별되며, 이 경로는 API의 엔드포인트와 결합되어 웹에서 리소스의 고유한 주소를 제공합니다. 예를 들어, Calendars는 캘린더 목록에 해당하는 리소스의 이름이며 해당 경로는 /calendars입니다.
작업은 리소스에서 수행할 수 있는 동작입니다. 가장 일반적인 작업은 GET(읽기), POST(생성), PUT(업데이트) 및 DELETE입니다. 예를 들어, List all Calendars는 Calendars 리소스에서 GET 메서드를 사용하는 작업의 이름입니다.
데이터 유형은 네트워크를 통해 교환되는 실제 데이터에 대한 설명입니다. 예를 들어, Calendar는 이름, 소유자 및 여기에 속한 이벤트에 대한 참조와 같은 Calendar의 모든 속성을 설명하는 데이터 유형의 이름입니다. List all Calendars 작업은 Calendar 데이터 유형의 목록을 반환합니다.
구성 요소는 API 정의 전체에서 재사용할 수 있는 요소입니다. 예를 들어, 여러 작업에서 동일한 쿼리 매개 변수를 사용해야 하는 경우 이를 구성 요소로 생성하고 필요한 만큼 많은 작업에서 참조할 수 있습니다.

API를 구성하는 다른 유용한 요소가 있습니다.

엔드포인트는 웹에서 API의 기본 진입점입니다. 엔드포인트는 HTTPS와 같은 체계와 www.calendar-api.com과 같은 호스트로 구성됩니다.
텍스트 블록을 사용하여 API 설계의 어느 곳에나 배치할 수 있는 텍스트(마크다운 포함)를 자유롭게 입력할 수 있습니다. 텍스트 블록을 사용하여 인증 및 오류 처리와 같은 횡단적 주제를 설명합니다.
섹션은 리소스와 데이터 유형을 의미 있게 그룹화하는 데 사용됩니다. 이를 사용하여 API 설계를 더 명확하고 개발자 친화적으로 만듭니다. 왼쪽 패널의 섹션으로 요소를 끌어서 놓기할 수 있으며 섹션 간의 순서를 바꿀 수도 있습니다.

API Designer에서는 오른쪽 상단의 새로 만들기 메뉴에서 이러한 요소를 생성할 수 있습니다.

서버 URL은 일반 정보 화면에서 생성됩니다. 서버 URL은 게시됨 또는 게시되지 않음일 수 있습니다. 게시된 경우 라이브 문서에 나타납니다.

이 페이지 또는 해당 콘텐츠에서 오타, 누락된 단계 또는 기술적 오류와 같은 문제를 발견하면 알려 주십시오!