Rest API 설계시 네이밍과 기본규칙

RestfulAPI 네이밍과 기본규칙

 

Restful API설계를 위한 네이밍규칙

Restful API는 URI를 통해 리소스를 식별합니다.

• 통합 자원 식별자(Uniform Resource Identifier, URI)는 인터넷에 있는 자원을 나타내는 유일한 주소
  • Uniform: 리소스를 식별하는 통일된 방식
  • Resource: URI로 식별 가능한 모든 종류의 자원을 지칭
  • Identifier: 다른 항목과 구분하기 위해 필요한 정보

이러한 리소스를 더 명확하게 식별하기 위해 네이밍 규칙이 필요합니다

 

명사를 사용할 것

Restful API는 명사 리소스를 참조해야함

리소스를 세가지 카테고리에 따라 하나의 원형으로 만들어야한다

 

 문서

하나의 파일, 인스턴스, 데이터베이스 레코드

→ 문서 리소스를 표시하려면 단수형을 사용

<http://api.example.com/device-management/managed-devices/{device-id}>
<http://api.example.com/user-management/users/{id}>
<http://api.example.com/user-management/users/admin>

 

컬렉션

서버가 관리하는 리소스 디렉토리

→ 계층 구조로 표현 가능하며 하위 디렉토리를 표현할 때도 복수형을 가진다.

여러 개체의 집합이며 각 개체는 고유한 식별자를 가진다

→ 컬렉션 리소스를 표시하려면 복수형을 사용

/device-management/managed-devices
/user-management/users
/user-management/users/{id}/accounts

 

스토어

클라이언트가 관리하는 자원 저장소

URI는 리소스가 처음 저장소에 저장될 때 클라이언트에 의해 선택됨

정적 컨텐츠 관리, 원격 파일 관리

→ 저장소 리소스 원형은 복수형을 사용

REST API URI Naming Conventions and Best Practices

 

일관성 갖추기

슬래시를 사용하여 계층관계 구성

/device-management
/device-management/managed-devices

 

URI 마지막은 슬래시를 사용하지 않는다

<http://api.example.com/device-management/managed-devices/> (x)

 

가독성을 높이고자한다면 하이픈(-)사용

<http://api.example.com/device-management/managed-devices>

 

밑줄은(_)사용하지 않는다

URI는 무조건 소문자를 사용

카멜, 스네이크 케이스 등을 적용하지 않는다

<http://api.example.org/my-folder/my-doc>

 

파일 확장자는 사용하지 않는다

/device-management/managed-devices.xml

 

URI에 CRUD 함수 이름을 사용하지 않는다

어떤 CRUD 기능이 수행되는지는 HTTP 요청 메소드를 사용해야한다

HTTP GET /device-management/managed-devices  			//Get all devices
HTTP POST /device-management/managed-devices  			//Create new
HTTP GET /device-management/managed-devices/{id}  		//Get device for given Id
HTTP PUT /device-management/managed-devices/{id}  		//Update device for given Id
HTTP DELETE /device-management/managed-devices/{id}  	//Delete device for given Id

 

URI 컬렉션을 사용하여 필터를 적용할 때 쿼리를 사용

특정 리소스 속성을 기반으로 정렬, 필터링 또는 제한되는 리소스 컬렉션이 필요한 경우 새 API를 생성하는 것이 아닌 쿼리 매개변수로 전달한다

/device-management/managed-devices
/device-management/managed-devices?region=USA
/device-management/managed-devices?region=USA&brand=XYZ
/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date

 

URI에 동사를 사용하지 않는 이유

Rest 방식은 HTTP 메서드를 통해 리소스에 대한 작업을 수행하는 동사역할을 한다.

동시에 URI가 동사를 사용하는 경우는 JSON or XML같은 RPC 형식의 메서드를 호출하는 경우이다.

 

코드번호에 대한 기본규칙

정보를 제공하는 응답(무시), 성공적인 응답, 리다이렉트, 클라이언트 에러, 그리고 서버 에러 5가지로 나뉘어진다

• 1XX 코드는 주로 임시, 확인용 응답으로 사용됨
• 2XX 코드는 성공
• 3XX 코드는 URL 리디렉션
• 4XX 코드는 클라이언트 오류
• 5XX 코드는 서버 오류

HTTP Status Codes - REST API Tutorial

 

HTTP 상태 코드 - HTTP | MDN

 

폴더 설계에 대한 고민 (컴포넌트, api폴더)

수정

├── comments
│   └── [id]
│       └── index.ts // comments api
├── games.ts
├── images
│   └── [id]
│       └── index.ts // images / HTTP 메서드를 통한 구분

- 태그로 분류
/**
 * @swagger
 * /api/test:
 *   get:
 *	   tags:
 *       - 태그입니다
 *     description: Return Hello, world
 *     responses:
 *       200:
 *         description: hello world
 */