API 스타일 가이드

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

이 스타일 가이드는 API 개발에 대한 모범 사례를 권장합니다. GraphQL 및 REST API # 고객에게 두 가지 유형의 API를 제공합니다: REST API GraphQL API 두 API를 병렬로 지원하는 기술적 부담을 줄이기 위해, 가능한 한 많은 구현을 공유해야 합니다. 예를 들어, 동일한 서비스 를 공유할 수 있습니다. 프론트엔드 # 프론트엔드에서 개발할 때 어떤 API를 사용할지에 대한 자세한 내용은 프론트엔드 가이드 를 참고합니다. 인스턴스 변수 # 인스턴스 변수는 사용하지 않습니다. 인스턴스 변수를 사용할 필요가 없으며(Rails 뷰에서처럼 접근할 필요가 없습니다), 로컬 변수로 충분합니다. 엔티티 # 엔드포인트의 페이로드를 표현할 때는 항상 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 엔티티 참조 문자열 형태의 임의의 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' } 영향도가 큰 엔티티와 기능 범위 엔티티 # UserBasic · ProjectIdentity · Commit 과 같은 일부 기반 엔티티는 많은 API 엔드포인트에 포함되거나 중첩되어 있습니다. 이런 엔티티 중 하나에 expose 호출을 하나 추가하면, 그 엔티티를 직접 또는 전이적으로 사용하는 모든 엔드포인트의 JSON 응답이 커집니다. 예를 들어 UserBasic 에 expose 호출을 하나 추가하면 212개 엔드포인트에, CustomAttribute 에 추가하면 238개 엔드포인트에 영향을 미칩니다. API 응답 페이로드가 통제 없이 커지는 것을 막기 위해, 영향도