스크립팅된 REST API 모범 사례
스크립트된 REST API를 디자인하고 구현할 때 다음 지침을 따르십시오.
REST API 규칙 따르기
REST API 표준을 사용하여 클라이언트에 일관되고 사용하기 쉬운 인터페이스를 제공합니다. REST API 규칙은 각 메서드 유형에 대한 특정 동작을 정의합니다. 다음 가이드라인을 API 설계의 시작점으로 사용합니다.
- GET 운영은 데이터만 쿼리합니다. GET 요청은 데이터를 수정해서는 안 됩니다.
- POST 운영은 새 기록을 생성하지만 기존 기록을 수정하지는 않습니다.
- PUT 및 PATCH 작업은 기존 기록을 수정합니다.
- DELETE 운영은 기록을 삭제합니다.
버전 관리를 사용하여 API 변경 제어
버전 관리를 사용하여 새 기능을 구현하고 기존 통합의 중단을 방지합니다. API에 중요한 기능 변경 사항을 도입하는 경우 먼저 새 버전의 API를 만듭니다. 게시된 버전에서 기존 통합을 중단하는 동작을 도입하지 마십시오.
버전 관리를 사용하면 기존 클라이언트를 손상시키지 않고 API에 중요한 변경 사항을 구현할 수 있습니다. 그런 다음 기존 클라이언트가 자신의 속도에 맞게 업그레이드하도록 허용하면서 새 클라이언트에 대해 새 버전의 API를 릴리스할 수 있습니다.
클라이언트가 버전별 API를 사용하도록 권장하거나 기본 버전 없이 API를 구성하여 클라이언트가 버전을 지정하도록 강제합니다. 기존 버전에 선택적 매개 변수를 추가하여 새로운 선택적 동작을 사용할 수 있도록 할 수도 있습니다.
정보가 포함된 HTTP 상태 코드 반환
요청자에게 요청의 성공 또는 실패를 알리는 상태 코드를 반환합니다. 클라이언트가 요청 결과를 이해하는 데 도움이 되는 HTTP 상태 코드를 반환합니다. 일반적인 상태 코드에 대한 다음 지침을 사용합니다.
| 상태 코드 | 설명 |
|---|---|
| 200 | 요청이 성공적으로 완료되었음을 나타냅니다. |
| 201 | 기록이 성공적으로 만들어졌음을 나타냅니다. |
| 204 | 기록이 성공적으로 삭제되었음을 나타냅니다. |
| 40배(401, 404) | 400 범위의 상태 코드는 잘못된 요청 구문의 경우 400과 같은 클라이언트 오류를 나타냅니다. |
| 50X (500, 503) | 500 범위의 상태 코드는 서버 오류가 발생했음을 나타냅니다. 클라이언트 요청이 유효하거나 유효하지 않을 수 있지만 서버에서 문제가 발생하여 요청을 처리할 수 없습니다. |
유용한 오류 정보 반환
API 설명서를 참조할 필요 없이 클라이언트가 문제를 이해할 수 있도록 오류 메시지에 충분한 정보를 제공합니다. 오류 응답에는 유용한 오류 메시지와 오류 상태 코드가 포함되어야 합니다.
예를 들어 클라이언트가 존재하지 않는 레코드를 쿼리할 때 "지정된 레코드가 존재하지 않습니다. 404 상태 코드와 함께 ID가 <id 값>인 기록이 애플리케이션에 있는지 확인합니다.
스크립팅된 REST API 기능에는 일반적으로 발생하는 오류에 사용할 수 있는 몇 가지 미리 구성된 오류 개체와 미리 구성된 오류 개체가 요구 사항을 충족하지 않을 때 사용할 수 있는 사용자 지정 가능한 ServiceRequest 오류 개체가 포함되어 있습니다.
접근 통제 적용 및 테스트
기존 접근 제어를 적용하고 데이터를 수정하기 위한 추가 접근 권한을 요구합니다. API에 액세스하기 위해 인증을 요구하는 것 외에도 데이터에 액세스하기 위한 권한 부여가 필요합니다. 스크립팅된 REST API 스크립트에서 GlideRecordSecure API를 사용합니다. 이 API는 기본 데이터에 정의된 액세스 제어가 요청하는 사용자에게 적용되도록 합니다.
데이터를 수정하는 작업에 대한 추가 액세스 제어가 필요합니다. PUT, POST 및 DELETE와 같은 요청에는 GET보다 높은 수준의 액세스가 필요합니다. 더 엄격한 ACL을 요구하도록 이러한 API 자원을 구성합니다.
API를 릴리스하기 전에 액세스 제어(인증 및 권한 부여)를 테스트합니다.
기능 확인을 위한 테스트 빌드
개발 프로세스의 일부로 스크립트된 REST 웹 서비스 기능을 확인하는 테스트를 빌드합니다. 반복 가능한 테스트를 사용하여 API가 예상대로 작동하는지 확인합니다. 또한 테스트를 통해 변경한 내용이 버전을 릴리스한 후 예상되는 API 동작에 영향을 주지 않는지 확인할 수 있습니다. 자동화된 테스트를 지원하는 REST 클라이언트 애플리케이션(예: Postman)을 사용하여 테스트를 용이하게 할 수 있습니다.
테스트는 구현하는 각 리소스에 적합한 응답 코드, 헤더 및 본문 콘텐츠의 유효성을 검사해야 합니다. 또한 테스트를 사용하여 인증 요구 사항의 유효성을 검사하고 오류가 유용한 응답을 반환하는지 확인할 수 있습니다.