스크립트 기반 REST API 모범 사례

  • 릴리스 버전: Zurich
  • 업데이트 날짜 2025년 07월 31일
  • 소요 시간: 3분

    • 스크립트된 REST API를 설계하고 구현할 때 다음 지침을 따릅니다.

    REST API 규칙 따르기

    REST API 표준을 사용하여 클라이언트에 일관되고 사용하기 쉬운 인터페이스를 제공합니다. REST API 규칙은 각 메서드 유형에 대한 특정 동작을 정의합니다. 다음 가이드라인을 API 설계의 시작점으로 사용하십시오.

    • GET 작업은 데이터만 쿼리합니다. GET 요청은 데이터를 수정해서는 안 됩니다.
    • POST 운영은 새 기록을 생성하지만 기존 기록은 수정하지 않습니다.
    • PUT 및 PATCH 운영은 기존 기록을 수정합니다.
    • DELETE 작업은 레코드를 삭제합니다.

    버전 관리를 사용하여 API에 대한 변경 제어

    버전 관리를 사용하여 새 기능을 구현하고 기존 통합이 중단되지 않도록 합니다. API에 중요한 기능 변경을 도입하는 경우 먼저 API의 새 버전을 만듭니다. 게시된 버전에서 기존 통합을 중단하는 동작을 도입하지 마십시오.

    버전 관리를 사용하면 기존 클라이언트를 손상시키지 않고 API에 중요한 변경 사항을 구현할 수 있습니다. 그런 다음 기존 클라이언트가 원하는 속도로 업그레이드할 수 있도록 하면서 새 클라이언트에 대한 새 버전의 API를 릴리스할 수 있습니다.

    클라이언트가 버전별 API를 사용하거나 기본 버전 없이 API를 구성하여 클라이언트가 버전을 지정하도록 강제합니다. 기존 버전에 선택적 매개변수를 추가하여 새로운 선택적 동작을 사용할 수 있도록 할 수도 있습니다.

    유익한 HTTP 상태 코드 반환

    요청자에게 요청의 성공 또는 실패를 알리는 상태 코드를 반환합니다. 클라이언트가 요청의 결과를 이해하는 데 도움이 되는 HTTP 상태 코드를 반환합니다. 일반적인 상태 코드에 대해 다음 지침을 사용합니다.

    표 1. 공통 상태 코드
    상태 코드 설명
    200 요청이 성공적으로 완료되었음을 나타냅니다.
    201 기록이 성공적으로 생성되었음을 나타냅니다.
    204 기록이 성공적으로 삭제되었음을 나타냅니다.
    40배속 (401, 404) 400 범위의 상태 코드는 클라이언트 오류를 나타냅니다(예: 잘못된 요청 구문의 경우 400).
    50배(500, 503) 500 범위의 상태 코드는 서버 오류가 발생했음을 나타냅니다. 클라이언트 요청이 유효하거나 유효하지 않을 수 있지만 서버에 문제가 발생하여 요청을 처리할 수 없습니다.

    유용한 오류 정보 반환

    클라이언트가 API 설명서를 참조하지 않고도 문제를 이해할 수 있도록 오류 메시지에 충분한 정보를 제공합니다. 오류 응답에는 유용한 오류 메시지와 오류 상태 코드가 포함되어야 합니다.

    예를 들어 클라이언트가 존재하지 않는 레코드를 쿼리할 때 "지정된 레코드가 없습니다. 404 상태 코드와 함께 ID가 <id value>"인 기록이 애플리케이션에 있는지 확인하십시오.

    스크립트된 REST API 기능에는 일반적으로 발생하는 오류에 사용할 수 있는 몇 가지 미리 구성된 오류 객체와 미리 구성된 오류 객체가 필요에 맞지 않을 때 사용할 수 있는 사용자 지정 가능한 ServiceRequest 오류 객체가 포함되어 있습니다.

    접근 제어 적용 및 테스트

    기존 접근 제어를 적용하고 데이터를 수정하려면 추가 접근 권한이 필요합니다. API에 액세스하려면 인증을 요구하는 것 외에도 데이터에 액세스하려면 권한 부여가 필요합니다. 스크립트된 REST API 스크립트에서 GlideRecordSecure API를 사용합니다. 이 API는 기본 데이터에 정의된 액세스 제어가 요청하는 사용자에게 적용되도록 합니다.

    데이터를 수정하는 작업에 대해 추가 접근 제어가 필요합니다. PUT, POST 및 DELETE와 같은 요청에는 GET보다 높은 수준의 액세스 권한이 필요합니다. 더 엄격한 ACL을 요구하도록 이러한 API 자원을 구성합니다.

    API를 릴리스하기 전에 인증 및 권한 부여와 같은 접근 제어를 테스트합니다.

    기능 확인을 위한 빌드 테스트

    개발 프로세스의 일부로 스크립트된 REST 웹 서비스 기능을 검증하는 테스트를 빌드합니다. 반복 가능한 테스트를 사용하여 API가 예상대로 작동하는지 확인합니다. 또한 테스트를 통해 변경 사항이 버전 릴리스 후 예상되는 API 동작에 영향을 미치지 않도록 할 수 있습니다. 자동화된 테스트를 지원하는 REST 클라이언트 애플리케이션(예: Postman)을 사용하여 테스트를 용이하게 할 수 있습니다.

    테스트는 구현하는 각 자원에 대해 적절하게 응답 코드, 헤더 및 본문 내용의 유효성을 검사해야 합니다. 또한 테스트를 사용하여 인증 요구 사항의 유효성을 검사하고 오류가 유용한 응답을 반환하는지 확인할 수 있습니다.