REST API design guide

REST API Design 가이드는 REST API Design Guidance - Code With Engineering Playbook 같은 훌륭한 Article이 있습니다만, REST 가이드를 잘 유지하는 게 힘든지 아니면 Graph API 등의 트렌드와 맞지 않는지 해당 가이드는 Deprecate 되었네요. 대신에 다음과 같은 Azure의 가이드들이 일부 대체합니다.

1. 웹 API 디자인 모범 사례 - Azure Architecture Center | Microsoft Learn
2. api-guidelines/azure/Guidelines.md at vNext · microsoft/api-guidelines · GitHub

 

실제로 개발자들의 API를 리뷰 해 보면 단지 CRUD를 위해서 POST/GET/PATCH/DELETE method를 쓰는 것 이외에 선택해야 하는 부분들이 많이 있는데, 그 부분들에 대해서 제가 주로 주는 가이드 들입니다.

 

1. REST API에서 가장 중요한 것은 ID 입니다

REST API는 특정한 Resource 위주로 설계되고, 이 Resource에 대한 ID를 어떻게 선택하느냐가 가장 중요합니다.

ID 설계 시 다음의 내용을 지켜주세요.

1. ✅ DO ID는 자체적으로 발급하는 Identifier (구분자) 입니다. 내가 생성해서 Resource를 제공해주기 때문에 해당 ID도 직접 발급 해 주게 됩니다.
2. ✅ DO ID는 URL frieldly해야 합니다. REST style 상 path에도 들어갈 수 있기 때문에 대소문자 구분하지 않는 alphanumeric을 권장하고, random uuid를 위해서 - 를 사용하는 것은 바람직하지는 않지만 허용 가능합니다. _ 문자는 권장하지 않습니다.
3. ⛔ DO NOT 주민등록정보나 SSN(Social Security Number) 같은 개인정보는 REST에서의 ID로 사용하면 안됩니다. 해당 정보가 URL에 노출되게 되고, 암호화 요구사항에 따라서 ID 체계가 영향을 받을 수 있습니다.

 

2. API 서버에의 HTTP Status Code 에러는 400/409입니다

401이나 429는 각각의 Micro Service 보다는 앞 단의 API Gateway나 인증 서버에서 주로 제공하고, 개별 서비스에서는 Client에서 수정해야 하는 문제는 400, 서버의 정책 상 제약은 409으로 응답합니다.

403이나 404는 권장하지는 않지만 필요한 경우에는 사용 할 수 있습니다.

 

3. POST와 PUT은 Idempotence를 고려하세요

REST Style에서 새로운 항목을 생성 할 떄에 201 Created를 반환하라고 많은 가이드 들이 있는데, 이 때에 ID를 누가 만드는지, 그리고 Idempotence(역등성)을 고민해야 합니다.

이렇게 되는 이유는 ID를 생성 할 때마다 새로 생성한다면 Idempotent 하지 않은데, ID를 자체 생성하지 않고 다른 Micro Service의 것을 재사용하는 구조라면 동일한 ID에 대해서 동일한 Resource가 반환되어야 합니다.

즉, 다음과 같이 정리할 수 있습니다.

1. 자체적으로 Resoure를 생성한다 → POST, 동일한 요청에 새 Resource/ID 생성
2. 생성 시 ID를 받는다 → PUT, 동일한 ID의 요청에 동일한 응답을 반환해서 Idempotence

 

4. REST에서 Request/Response의 Body Entity는 동일한 Model을 사용합니다

POST/PUT/GET/PATCH 등은 동일한 Resource를 Create, Read, Update 하는 동작만 하기 때문에 다음 경우에는 동일한 Request/Response를 사용할 수 있습니다.

1. PUT request/response
2. PATCH response
3. GET response
4. POST response