스크립트 기반 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). |
| 50배(500, 503) | 500 범위의 상태 코드는 서버 오류가 발생했음을 나타냅니다. 클라이언트 요청이 유효하거나 유효하지 않을 수 있지만 서버에서 문제가 발생하여 요청을 처리할 수 없습니다. |
유용한 오류 정보 반환
클라이언트가 API 설명서를 참조하지 않고도 문제를 이해할 수 있도록 오류 메시지에 충분한 정보를 제공합니다. 오류 응답에는 유용한 오류 메시지와 오류 상태 코드가 포함되어야 합니다.
예를 들어 클라이언트가 존재하지 않는 기록을 쿼리하면 "지정된 기록이 없습니다. ID가 <id 값>인 기록이 애플리케이션에 있어야 합니다." 그리고 404 상태 코드.
스크립팅된 REST API 기능에는 일반적으로 발생하는 오류에 사용할 수 있는 미리 구성된 여러 오류 개체와 미리 구성된 오류 개체가 필요에 맞지 않을 때 사용할 수 있는 사용자 지정 가능한 ServiceRequest 오류 개체가 포함되어 있습니다.
접근 제어 적용 및 테스트
기존 접근 제어를 적용하고 데이터를 수정하려면 추가 접근 권한이 필요합니다. API에 액세스하려면 인증을 요구하는 것 외에도 데이터에 액세스하려면 권한 부여가 필요합니다. 스크립팅된 REST API 스크립트에서 GlideRecordSecure API를 사용합니다. 이 API를 사용하면 기본 데이터에 정의된 접근 제어가 요청 사용자에게 적용됩니다.
데이터를 수정하는 작업에 대해 추가 접근 제어가 필요합니다. PUT, POST 및 DELETE와 같은 요청에는 GET보다 높은 수준의 액세스 권한이 필요합니다. 보다 엄격한 ACL을 요구하도록 이러한 API 자원을 구성합니다.
API를 릴리스하기 전에 인증 및 권한 부여 모두에서 접근 제어를 테스트합니다.
기능 검증을 위한 테스트 빌드
개발 프로세스의 일부로 스크립팅된 REST 웹 서비스 기능을 확인하는 테스트를 빌드합니다. 반복 가능한 테스트를 사용하여 API가 예상대로 작동하는지 확인합니다. 또한 테스트를 수행하면 변경 내용이 버전 릴리스 후 예상되는 API 동작에 영향을 주지 않는지 확인하는 데 도움이 됩니다. Postman과 같이 자동화된 테스트를 지원하는 REST 클라이언트 애플리케이션을 사용하여 테스트를 용이하게 할 수 있습니다.
테스트는 구현하는 각 자원에 적합한 응답 코드, 헤더 및 본문 콘텐츠를 확인해야 합니다. 또한 테스트를 사용하여 인증 요구 사항의 유효성을 검사하고 오류가 유용한 응답을 반환하는지 확인할 수 있습니다.