🔥 규칙

714자

9분

강의 목차

1. 애플리케이션 계층 프로토콜

이 문서는 클라이언트-서버 간 상호작용을 설명할 때 다음과 같은 규칙을 사용합니다.

1. 애플리케이션 계층 프로토콜

클라이언트와 서버는 https URI 스키마를 사용해 Transport Layer Security (TLS)로 보안된 연결을 통해 통신해야 합니다.

예제에서 HTTP 1.1을 사용하는 것은 규범적이지 않습니다. 클라이언트와 서버는 이 명세에 따라 HTTP 프로토콜의 어떤 버전으로도 통신할 수 있습니다.

2. 인증

서버는 패키지와 패키지 릴리스에 대한 정보에 접근하기 위한 클라이언트 요청에 인증을 요구할 수 있습니다.

클라이언트가 인증이 필요한 엔드포인트로 자격 증명 없이 요청을 보내면 서버는 401 (Unauthorized) 상태 코드로 응답해야 합니다. 클라이언트가 유효한 자격 증명을 제공하지만 요청한 리소스에 접근할 권한이 없는 경우 서버는 404 (Not Found) 또는 403 (Forbidden) 상태 코드로 응답할 수 있습니다.

서버는 원하는 어떤 인증 모델이라도 사용할 수 있습니다. 그러나 OAuth 2.0과 같은 범위가 지정되고 취소 가능한 권한 부여 프레임워크의 사용이 권장됩니다.

3. 오류 처리

서버는 RFC 7807에 설명된 대로 "problem details" 객체를 사용하여 클라이언트에 오류를 전달해야 합니다. 예를 들어, 클라이언트가 존재하지 않는 패키지 릴리스를 요청하면 다음과 같은 응답을 받게 됩니다:

HTTP/1.1 404
Content-Version: 1
Content-Type: application/problem+json
Content-Language: en

{
   "detail": "release not found"
}text

4. 요청 제한

서버는 429 (Too Many Requests) 상태 코드로 응답하여 클라이언트가 하는 요청 수를 제한할 수 있습니다.

HTTP/1.1 429
Content-Version: 1
Content-Type: application/problem+json
Content-Language: en
Retry-After: 60

{
   "detail": "try again in 60 seconds"
}text

클라이언트는 재시도 요청으로 서버를 압도하는 것을 방지하기 위해 응답에 제공된 모든 Retry-After 헤더 값의 지침을 따라야 합니다. 클라이언트에서는 바람몰이 효과를 피하기 위해 재시도 로직에 무작위 지연시간을 도입하는 것이 좋습니다.

5. API 버전 관리

패키지 레지스트리 API는 버전이 있습니다.

API 버전 번호는 십진 정수로 지정됩니다. 이 제안서의 허용된 버전은 초기 버전인 1을 구성합니다. 이후 개정판에는 순차적으로 번호(2, 3 등)를 매겨야 합니다.

API 버전 번호는 주요 릴리스를 위해 Semantic Versioning 규칙을 따라야 합니다. 새 엔드포인트 추가, 기존 엔드포인트에 새 선택적 매개변수 추가 또는 이전 버전과 호환되는 방식으로 기존 엔드포인트에 새 정보 추가와 같은 비중단 변경 시에는 새 버전이 필요하지 않아야 합니다. 기존 엔드포인트를 제거하거나 이전 버전과 호환되지 않는 방식으로 변경하는 등의 중단 변경 사항은 반드시 새 버전에 해당해야 합니다.

클라이언트는 요청의 API 버전을 지정하기 위해 Accept 헤더 필드를 설정해야 합니다.

GET /mona/LinkedList/list HTTP/1.1
Host: packages.example.com
Accept: application/vnd.swift.registry.v1+json
text

유효한 Accept 헤더 필드 값은 다음 규칙으로 설명됩니다:

    version     = "1"       ; API 버전
    mediatype   = "json" /  ; JSON (기본 미디어 유형)
                  "zip"  /  ; 패키지 릴리스에 사용되는 Zip 압축 파일
                  "swift"   ; 패키지 매니페스트에 사용되는 Swift 파일
    accept      = "application/vnd.swift.registry" [".v" version] ["+" mediatype]text

서버는 응답의 해당 콘텐츠 유형으로 Content-Type 헤더 필드를 설정해야 합니다.

서버는 달리 명시되지 않는 한 응답의 API 버전 번호로 Content-Version 헤더 필드를 설정해야 합니다.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Version: 1
text

클라이언트가 Accept 헤더 없이 요청을 보내면 서버는 400 Bad Request 상태 코드로 응답하거나 자체적으로 선택한 API 버전을 사용하여 Content-Type과 Content-Version 헤더를 올바르게 설정해 요청을 처리할 수 있습니다.

클라이언트가 알 수 없거나 잘못된 API 버전을 지정하는 Accept 헤더와 함께 요청을 보내면 서버는 400 (Bad Request) 상태 코드로 응답해야 합니다.

HTTP/1.1 400 Bad Request
Content-Version: 1
Content-Type: application/problem+json
Content-Language: en

{
   "detail": "invalid API version"
}text

클라이언트가 유효하지만 지원되지 않는 API 버전을 지정하는 Accept 헤더와 함께 요청을 보내면 서버는 415 (Unsupported Media Type) 상태 코드로 응답해야 합니다.

HTTP/1.1 415 Unsupported Media Type
Content-Version: 1
Content-Type: application/problem+json
Content-Language: en

{
   "detail": "unsupported API version"
}text

6. 패키지 식별

패키지는 매니페스트의 종속성으로 외부 패키지를 선언할 수 있습니다. 각 패키지 종속성은 허용되는 버전에 대한 요구사항을 지정할 수 있습니다.

외부 패키지 종속성 자체에는 전이 종속성이라고 하는 하나 이상의 외부 패키지 종속성이 있을 수 있습니다. 여러 패키지에 공통 종속성이 있는 경우 Swift Package Manager는 패키지 해결이라는 프로세스에서 해당 패키지의 어떤 버전을 사용해야 하는지(지정된 모든 요구사항을 충족하는 버전이 있는 경우) 결정합니다.

각 외부 패키지는 scope.package-name 형식의 범위가 지정된 식별자로 고유하게 식별됩니다.

6.1 패키지 범위

범위는 패키지 레지스트리 내에서 관련 패키지에 대한 네임스페이스를 제공합니다. 패키지 범위는 영숫자와 하이픈으로 구성됩니다. 하이픈은 시작이나 끝 또는 범위 내에서 연속적으로 나타날 수 없습니다. 패키지 범위의 최대 길이는 39자입니다. 유효한 패키지 범위는 다음 정규식 패턴과 일치합니다:

A[a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38}ztext

패키지 범위는 대소문자를 구분하지 않습니다(예: mona ≍ MONA).

6.2. 패키지 이름

패키지의 이름은 범위 내에서 패키지를 고유하게 식별합니다. 패키지 이름은 영숫자, 밑줄 및 하이픈으로 구성됩니다. 하이픈과 밑줄은 시작이나 끝 또는 이름 내에서 연속적으로 나타날 수 없습니다. 패키지 이름의 최대 길이는 100자입니다. 유효한 패키지 이름은 다음 정규식 패턴과 일치합니다:

A[a-zA-Z0-9](?:[a-zA-Z0-9]|[-_](?=[a-zA-Z0-9])){0,99}ztext

패키지 이름은 대소문자를 구분하지 않습니다(예: LinkedList ≍ LINKEDLIST).

강의 내용

1. 애플리케이션 계층 프로토콜
2. 인증
3. 오류 처리
4. 요청 제한
5. API 버전 관리
6. 패키지 식별
6.1 패키지 범위
6.2. 패키지 이름