REST용 API 디자인 패턴

REST는 몇 달 후면 22세가 됩니다. Roy Fielding의 논문에 요약된 API 아키텍처 및 권장 사항 외에도 이제 20년 동안 실용적으로 적용할 수 있습니다. API 프로젝트를 설계할 때 수많은 다른 사람들이 이미 구현한 웹 서비스에 대한 REST 모범 사례 및 지침을 기반으로 구축하는 것이 좋습니다.

이 게시물은 사용자가 RESTful API가 무엇인지, 그리고 여러 범주에서 가장 일반적인 REST API 디자인 패턴, 개발 및 원칙을 배우는 데 도움이 됩니다. 새로 시작하는 대신 수천 개의 성공적인 API 회사의 API 지침 기반을 기반으로 구축하십시오. RESTful API를 구축해 보겠습니다.

🔗HTTP 메서드 및 상태 코드

REST API를 정의해 봅시다. RESTful API의 정의는 HTTP 프로토콜을 사용할 필요가 없음을 의미합니다. 그러나 이 둘은 함께 개발되었으며 거의 모든 RESTful API 코드는 HTTP에 의존합니다. 이러한 이유로 HTTP에서 이미 잘 정의된 기본 제공 메서드 및 상태 코드를 중심으로 API를 구성하는 것이 좋습니다. 다음은 HTTP REST API를 설계, 개발 및 생성하는 방법입니다.

REST API 설계를 위해 각 HTTP 요청에는 각 호출에 대한 많은 컨텍스트를 제공하는 "HTTP 동사"라고도 하는 메서드가 포함됩니다. 가장 일반적인 HTTP 메서드는 다음과 같습니다.

GET : API에서 데이터 읽기
POST : API에 새 데이터 추가
PUT : API로 기존 데이터 업데이트
PATCH : API로 기존 데이터의 하위 집합을 업데이트합니다.
DELETE : API에서 데이터(일반적으로 단일 리소스)를 제거합니다.

이 모든 것을 자세히 논의하지는 않겠지만 CRUD와 REST에 대한 자세한 내용은 CRUD API 디자인 에 대한 게시물을 확인하십시오 .

API를 설계할 때 RESTful API URL에 목적을 추가하는 대신 호출의 기본 목적을 표현하기 위해 이러한 메서드에 의존하고 싶을 것입니다. 우리는 그것에 대해 조금 더 알게 될 것입니다.

이러한 메서드가 클라이언트에서 서버로 요청 컨텍스트를 제공하는 것처럼 HTTP 상태 코드는 응답을 반대 방향으로 설명하는 데 도움이 됩니다.

몇 가지 일반적인 HTTP 상태 코드는 다음과 같습니다.

200 : 성공적인 요청, 종종 GET
201 : 생성 후 성공적인 요청, 일반적으로 POST
204 : 반환된 콘텐츠 없이 성공적인 요청, 일반적으로 PUT 또는 PATCH
301 : 다른 끝점으로 영구적으로 리디렉션
400 : 잘못된 요청(클라이언트가 요청을 수정해야 함)
401 : 승인되지 않음, 자격 증명이 인식되지 않음
403 : 금지됨, 자격 증명이 허용되지만 권한이 없음
404 : 찾을 수 없음, 리소스가 존재하지 않음
410 : 사라짐, 리소스가 이전에 존재했지만 지금은 없음
429 : 속도 제한에 사용되는 요청이 너무 많으며 재시도 헤더를 포함해야 합니다.
500 : 서버 오류, 일반적이며 대신 다른 500 수준 오류를 살펴볼 가치가 있습니다.
503 : 서비스를 사용할 수 없음, 재시도 헤더가 유용한 다른 서비스

고려해야 할 더 많은 HTTP 상태 코드와 메서드가 있지만 위의 목록은 대부분의 API에 대해 잘 이해할 수 있도록 합니다.

친근하고 일반적인 API 엔드포인트 이름 사용

웹 사이트의 API 끝점을 어떻게 찾고 결정합니까? REST API를 사용하는 일반적인 디자인 패턴은 리소스를 기반으로 엔드포인트를 구축하는 것입니다. 이들은 HTTP 메서드 동사에 대한 "명사"입니다. 이러한 이름이 설명적이면 API 디자인을 훨씬 더 쉽게 이해할 수 있습니다. API 디자인 예제의 경우 요리책 API에서 작업하는 경우 다음 API 엔드포인트 예제의 코드 예제는 /recipes/일 수 있습니다.

새 레시피를 추가하면 이를 엔드포인트에 POST합니다. 목록을 가져오려면 동일한 끝점에서 GET 메서드를 사용합니다. 특정 레시피를 검색하려면 URL의 식별자로 호출할 수 있습니다. /recipes/42

친숙한 REST 끝점 이름으로 특별히 피해야 할 한 가지는 요청에 대한 새로운 정보를 전달하지 않기 때문에 작업을 설명하는 것입니다.

예를 들어 엔드포인트 내의 동사(예: /getRecipes/)는 해당 컨텍스트를 제공하기 위해 HTTP 메서드에 의존하는 것과 반대로 실행됩니다. CRUD API 설계 권장 사항 게시물 은 복수형 및 버전 관리와 같은 인기 있는 주제를 포함하여 더 자세히 설명합니다.

GET 대 POST API 대량 작업

RESTful API를 설계할 때 호출의 기본 목적을 표현하기 위해 HTTP 메서드 및 모범 사례에 의존하고 싶을 것입니다. 이러한 이유로 단순히 데이터를 검색하기 위해 POST를 사용하고 싶지는 않습니다. GET이 데이터를 생성하거나 제거하는 것도 원하지 않습니다. 사용 사례를 검토하여 각 사용 시기를 결정해야 합니다. 다음은 귀하의 결정에 영향을 미치는 몇 가지 요소입니다.

GET 요청을 캐시할 수 있습니다.
GET 요청은 멱등적 입니다 (동일한 결과를 보장하면서 여러 번 호출할 수 있음).
GET 요청은 민감한 데이터를 처리할 때 사용해서는 안 됩니다.
GET 요청에는 길이 제한이 있습니다.
GET 요청은 데이터 검색에만 사용해야 합니다.
POST 요청은 캐시되지 않습니다(헤더에 지정되지 않은 경우).
POST 요청은 멱등성이 아닙니다.
POST 요청에는 데이터 길이에 대한 제한이 없습니다.

방법을 현명하게 선택하면 경로를 간결하게 유지하고 기본 RESTful API 관행을 따릅니다. 간단한 예를 살펴보겠습니다.

기본 CRUD 기능(만들기, 읽기, 업데이트, 삭제)을 구현하는 경로가 있다고 가정하면 다음 경로로 끝납니다.

[POST] /api/recipe - 레시피 생성
[GET] /api/recipe - 레시피 나열
[GET] /api/recipe/:id - ID로 레시피 가져오기
[PUT] /api/recipe/:id - ID로 레시피 업데이트
[DELETE] /api/recipe/:id - ID별로 레시피 삭제
[DELETE] /api/recipe - 대량 삭제 레시피

이 예에서는 실제로 "/api/recipes" 및 "/api/recipe/:id" 2개의 경로만 있습니다. POST만 사용한다면 6개의 다른 경로가 생깁니다.

성능 향상을 위한 캐시 데이터

캐싱은 불필요한 서버 이동을 부분적으로 제거합니다. 각각의 새 요청에 대한 쿼리를 보내는 대신 로컬 메모리에서 데이터를 반환하면 앱의 성능을 향상시킬 수 있습니다. GET 요청은 기본적으로 캐시 가능하지만 POST 요청의 경우 헤더에 캐시 요구 사항을 지정해야 합니다. 그러나 캐싱은 클라이언트의 브라우저에서 오래된 데이터로 이어질 수 있습니다. POST 헤더 에서 이를 처리하는 방법은 다음과 같습니다 .

만료

이 경우 캐시된 버전에 대한 절대 만료 시간을 지정합니다. 지정된 시간을 초과하는 모든 항목은 오래된 것으로 간주되며 원본 서버로 업데이트해야 합니다. 최대 1년 후의 시간을 지정할 수 있습니다.

캐시 제어

이 옵션을 사용할 때 max-age, must-revalidate 또는 no-transform과 같은 특정 지시문을 설정할 수 있습니다 .

마지막 수정

이 옵션을 사용하면 응답 헤더를 사용하여 캐싱 요구 사항을 결정합니다. 응답의 날짜 값은 초기 응답이 생성된 시기를 지정합니다. Last-Modified 날짜는 리소스와 연결된 응답이 마지막으로 변경된 날짜를 지정합니다. 최종 수정 날짜는 날짜 값보다 작을 수 없습니다.

API 매개변수를 사용한 향후 사용 사례 계획

순진하거나 단순한 API 설계는 위의 모든 지침을 따를 수 있지만 여전히 개발자에게 필요한 사용 사례를 지원하지 않습니다. API가 사용되는 방식을 철저히 이해하고 모의 API 서버 와 같은 공동작업자로부터 피드백을 받는 것이 중요합니다 .

종종 API가 구축된 후 사용 사례가 발견되면 엔지니어는 이러한 발굴된 요구 사항을 지원하기 위해 새로운 엔드포인트를 생성합니다. 예를 들어 요리책 API는 특정 카테고리의 레시피만 반환해야 하거나 준비 시간이 가장 짧은 레시피를 표시해야 할 수 있습니다. 중복 엔드포인트를 생성하는 대신 처음부터 스마트 매개변수를 계획하십시오.

API에 대해 고려해야 할 세 가지 일반적인 유형의 매개변수가 있습니다.

필터링 : 필드 나이를 매개변수로 사용하여 필터와 일치하는 결과만 반환합니다. 예를 들어:

GET /사용자?나이=30

페이지 매김 : 모든 것을 제공하여 클라이언트와 서버에 과부하를 주지 마십시오. 대신 제한을 설정하고 응답에 이전 및 다음 링크를 제공하십시오. 예:

GET /users?page=3&results_per_page=20

정렬 : 정렬 방법을 제공하거나 일부 사용 사례에서는 여전히 필요한 것을 찾기 위해 모든 결과를 페이징해야 합니다. 예:

GET /users?sort_by=first_name&order=asc

이 세 가지 접근 방식을 함께 사용하여 매우 구체적인 쿼리를 지원할 수 있습니다. 사용 사례를 이해하면 매개변수의 복잡성을 결정하는 데 도움이 됩니다.

기존 대회에서 차용

이 게시물은 전반적인 API 디자인 패턴을 다루기 위해 최선을 다하고 있지만 업계 또는 특정 기능에 특정한 표준 및 규칙을 살펴보고 싶을 것입니다. 완전히 고유한 API를 구축하는 사람은 거의 없기 때문에 다른 사람에게서 배울 점이 많습니다.

많은 API 표준이 REST API를 중심으로 구축되었습니다. 예를 들어 API에 대한 인증을 구현할 때 새로운 길을 개척하지 마십시오. 사용자 관련 데이터를 제공할 때 잘 알려진 OAuth 경로를 포함하여 API 인증 패턴에 대한 많은 옵션이 있습니다. API 헤더에 대한 표준과 JSON 및 XML과 같은 데이터 형식 및 모델에 대한 몇 가지를 찾을 수 있습니다.

고유한 고려 사항이 있는 마이크로서비스 API를 설계 할 수 있습니다 . 이 게시물에서 다루는 모든 내용이 여전히 적용될 가능성이 높지만 마이크로서비스를 설계할 때 더욱 주의를 기울여야 합니다. 각각은 그 자체로 의미가 있어야 하지만 조합(느슨한 결합)의 이점을 누릴 수 있습니다.

반면 오픈 뱅킹 API는 자체 처리가 필요합니다. 유럽 표준은 가장 성숙했으며 이러한 규정을 기반으로 하는 일련의 디자인 패턴을 가지고 있습니다.

귀하의 산업에는 고유한 표준 또는 규칙이 있을 수 있습니다. 은행 규정만큼 엄격하지 않더라도 개발자에게 이미 친숙한 패턴에 대해 적절한 고려를 할 가치가 있습니다.

OpenAPI 정의가 있는 문서

API를 설계할 때 OpenAPI 정의를 정보 소스로 유지하는 것이 매우 유용합니다 . 이전 Swagger 파일의 차세대 형식인 이 형식은 엔드포인트, 요청 데이터, 응답, 오류 코드 등을 설명합니다. 또한 API 수명 주기 전반에 걸쳐 도구를 사용하여 자동화하는 데 사용할 수 있습니다.

아마도 OpenAPI 문서의 가장 일반적인 용도는 API 문서 , 특히 API 참조를 생성하는 것입니다. 형식은 API를 호출할 수 있는 방법을 설명하므로 개발자가 API와 통합하는 데 필요한 모든 정보가 포함됩니다. 또한 일부 API 참조에는 오류 코드와 같은 필수 세부 정보가 포함되어 있지 않으므로 OpenAPI는 정확한 문서화를 권장합니다. 또한 API가 변경될 때마다 새 문서를 생성할 수 있으므로 항상 최신 상태를 유지할 수 있습니다.

또한 OpenAPI 정의를 사용하여 모의 HTTP 서버를 생성 할 수 있습니다 . 이를 통해 코드를 작성하기 전에 API를 시험해 볼 수 있습니다. 초기 피드백 또는 온라인 REST API 클라이언트의 요청 유효성 검사를 위해 팀 간에 인터페이스를 순환합니다.

이는 YAML 또는 JSON을 사용하여 OpenAPI 정의 파일을 생성할 수 있는 기계 판독 가능 API 정의의 두 가지 잠재적 용도입니다. 또는 시각적 OpenAPI 편집기를 사용하여 훨씬 빠르게 만들 수 있습니다. Stoplight Studio는 모든 git 저장소에서 기존 OpenAPI 파일을 읽을 수 있으며 아름다운 편집 환경 내에서 편집하거나 처음부터 시작할 수 있습니다.

일관성을 위해 스타일 가이드 사용

일부 디자인 패턴은 기본 설정의 문제입니다. 이상적으로는 API를 생성할 때마다 다시 방문하지 않고 조직의 접근 방식을 한 번에 체계화할 수 있습니다. 스타일 가이드는 API 디자인과 동일한 페이지에 회사를 유지할 수 있습니다. API 간에 일관성을 유지하는 것 외에도 단일 API 내에서 일관성을 유지하는 것이 훨씬 더 중요합니다.

일부 조직에서는 서면 API 스타일 가이드를 작성합니다. 인트라넷 내에서 쉽게 액세스할 수 있는 문서는 모든 사람이 이미 채택한 디자인 패턴을 이해하는 데 도움이 됩니다. 그러나 프로그래밍 방식으로 스타일 가이드를 적용하여 더 멀리 갈 수 있습니다. 오픈 소스 린터 와 같은 도구를 사용하여 OpenAPI 문서에 대한 규칙 세트를 정의할 수 있습니다.

API 스타일 가이드를 자동화하면 리소스 및 필드 이름, 대문자 형식, 구두점 사용 방법, 버전 관리 등 API 특성을 얼마든지 찾아볼 수 있습니다.

서면이든 프로그래밍 방식이든 스타일 가이드는 여기에서 다루는 디자인 패턴에 대한 자신만의 가이드라인이 됩니다. 조직에서 HTTP 메서드를 올바르게 사용하고, 적절한 상태 코드를 반환하고, 친숙한 엔드포인트 이름을 구현하고, 스마트 매개변수를 사용하고, 이미 식별한 기존 규칙에서 차용하도록 돕습니다.

환상적인 API를 만들고 API 디자인 아키텍처를 더 잘 이해할 준비가 되었으니 Stoplight의 API 디자인 관리 플랫폼 에서 세계 최고의 API 우선 회사에 합류하세요 . API RESTful 웹 서비스 예제 및 API REST 빌드의 모범 사례에 대한 자세한 내용은 REST에 대한 이 블로그를 확인하여 REST API를 빌드하는 방법에 대해 자세히 알아보세요.

출처 : https://blog.stoplight.io/api-design-patterns-for-rest-web-services?utm_source=pocket_saves