API 스타일 가이드

GitLab REST API 및 GraphQL API 개발 시 권장하는 모범 사례와 규칙을 설명합니다.

이 스타일 가이드는 API 개발에 대한 모범 사례를 권장합니다. GraphQL 및 REST API # 고객에게 두 가지 유형의 API를 제공합니다: REST API GraphQL API 두 API를 병렬로 지원하는 기술적 부담을 줄이기 위해, 가능한 한 많은 구현을 공유해야 합니다. 예를 들어, 동일한 서비스 를 공유할 수 있습니다. Frontend # 프론트엔드 개발 시 어떤 API를 사용할지에 대한 자세한 내용은 프론트엔드 가이드 를 참조하세요. 인스턴스 변수 # 인스턴스 변수를 사용하지 마세요. 인스턴스 변수는 필요하지 않습니다(Rails 뷰에서처럼 접근할 필요가 없습니다). 지역 변수를 사용하면 됩니다. Entities # 엔드포인트의 페이로드를 표시할 때는 항상 Entity 를 사용하세요. Entity 필드 정의 # Entity에 노출된 모든 필드는 유효한 타입을 포함하거나 참조해야 합니다. 다른 Entity 참조 # 다른 Entity를 참조하는 필드를 노출할 때는 using 옵션을 사용하세요. using 옵션은 API::Entities 클래스를 가리키는 상수만 허용합니다. 좋은 예시는 다음과 같습니다: expose :project, using: ::API::Entities::BasicProjectDetails 유효한 필드 타입 # 필드 타입은 문자열로 지정해야 합니다. 다음 타입이 허용됩니다: 카테고리 타입 스칼라 Integer, Float, BigDecimal, Numeric, Date, DateTime, Time, String, Symbol, Boolean 구조체 Hash, Array, Set 특수 JSON, File Entity 참조 임의의 API::Entities::* 클래스 (문자열로) 필드 타입 정의 # 필드 타입은 documentation 해시에 정의해야 합니다: expose :id, documentation: { type: 'Integer', example: 1 } expose :name, documentation: { type: 'String', example: 'John Doe' } expose :active, documentation: { type: 'Boolean', example: true } expose :project, documentation: { type: 'API::Entities::BasicProject'} 고영향 Entity와 기능 범위 Entity # UserBasic , ProjectIdentity , Commit 과 같은 일부 기반 Entity는 여러 API 엔드포인트에 임베드되거나 중첩됩니다. 이러한 Entity 중 하나에 단 하나의 expose 호출을 추가하면 해당 Entity를 직접 또는 간접적으로 사용하는 모든 엔드포인트의 JSON 응답이 커집니다. 예를 들어, UserBasic 에 단 하나의 expose 호출을 추가하면 212개의 엔드포인트에 영향을 미치고, CustomAttribute 에 추가하면 238개에 영향을 미칩니다. API 응답 페이로드의 통제되지 않는 증가를 방지하