22 Best Practices to Take Your API Design Skills to the Next Level

📎 22 Best Practices to Take Your API Design Skills to the Next Level

• 마이크로서비스의 세계에서는 백엔드 API에 대한 일관된 설계가 필수적입니다.

 

https://betterprogramming.pub/22-best-practices-to-take-your-api-design-skills-to-the-next-level-65569b200b9

22 Best Practices to Take Your API Design Skills to the Next Level

위 원문을 번역한 포스팅입니다.

 

 

 

First, Some Terminology

---

Resource Oriented Design 이라고 불리는 모든 API의 디자인은 아래 세 가지 핵심 개념으로 구성이 됩니다.

• Resource(리소스): 리소스는 User와 같은 데이터의 조각입니다. 
• Collection(컬렉션): 컬렉션은 User의 리스트(목록)과 같은 리소스의 그룹을 의미합니다.
• URL: 리소스 또는 컬렉션의 위치를 식별합니다. (ex: /user)

 

 

1. Use kebab-case for URLs

---

 

주문 목록을 가져오려는 경우 다음과 같은 좋은 예시와 나쁜 예시가 존재합니다.

 

Good:

/system-orders

 

Bad:

/systemOrders
/system_orders

 

 

2. Use camelCase for Parameters

---

특정 상점에서 제품을 가져오는 경우 다음과 같은 좋은 예시와 나쁜 예시가 존재합니다.

 

Good:

/system-orders/{orderId}

 

Bad:

/system-orders/{order_id}
/system-orders/{OrderId}

 

 

3. Plural Name to Point to a Collection

---

시스템의 모든 유저(복수형)를 조회하기 위해 다음과 같은 좋은 예시와 나쁜 예시가 존재합니다.

 

Good:

GET /users

 

Bad:

GET /user
GET /User

 

 

4. URL Starts With a Collection and Ends With an Identifier

---

컨셉을 독특하고 일관되게 유지하려는 경우 식별자로 끝나야 합니다.

 

Good:

GET /shops/:shopId/ 
GET /category/:categoryId

 

Bad:

GET /shops/:shopId/category/:categoryId/price

 

 

5. Keep Verbs Out of Your Resource URL

---

URL에서 의도를 표현하기 위해 동사를 사용하지 마세요. 대신, 적절한 HTTP 메소드를 사용하여 작업을 설명합니다.

 

Good:

PUT /user/{userId}

 

Bad:

POST /updateuser/{userId}
GET /getusers

 

 

6. Use Verbs for Non-Resource URL

---

작업만 반환하는 엔드포인트가 있습니다. 이러한 경우 동사를 사용할 수 있습니다.

• 예를 들어, 사용자에게 경고를 다시 보내려는 경우

 

Good:

POST /alerts/245743/resend

위 URL은 CRUD 작업이 아니라 시스템에서 특정 작업을 수행하는 기능으로 간주됩니다.

 

 

7. Use camelCase for JSON property

---

요청 본문 또는 응답이 JSON인 시스템을 구축하려는 경우, 속성 필드는 카멜케이스여야 합니다.

 

Good:

{
   userName: "Mohammad Faisal"
   userId: "1"
}

 

Bad:

{
   user_name: "Mohammad Faisal"
   user_id: "1"
}

 

 

8. Monitoring

---

RESTful HTTP 서비스는 /health, /version, /metrics의 API 엔드포인트를 구현해야 하며, 이는 다음 정보를 제공합니다.

 

/health

• /health의 요청에 대해 200 OK의 상태코드로 응답합니다.

 

/version

• /version의 요청에 대해 버전 번호로 응답합니다.

 

/metrics

• /metrics API는 평균 응답 시간과 같은 다양한 매트릭을 제공합니다.

 

 

9. Don't Use table_name for the Resource Name

---

테이블 이름을 리소스 이름으로 사용하지 마세요. 장기적으로는 위험할 수 있습니다.

 

Good:

product-orders

 

Bad:

product_orders

 

 

10. API 디자인 도구 사용

---

다음과 같은 좋은 문서화를 위한 좋은 API 디자인툴이 많이 존재합니다.

• API Blueprint
• Swagger

훌륭하고 상세한 문서화는 API 소비자에게 훌륭한 사용자 경험(UX)를 제공합니다.

 

 

11. Use Simple Ordinal Number as Version

---

항상 API에 버저닝을 사용하고, 가장 높은 범위를 가지도록 하세요. 버전 번호는 v1, v2 등등이어야 합니다.

 

Good:

http://api.domain.com/v1/shops/3/products

API가 외부 엔티티에서 사용중인 경우 엔드포인트를 변경하면 기능이 중단될 수 있으므로 항상 API에 대한 버저닝을 사용하세요.

 

 

12. Include Total Number of Resources in Your Response

---

API가 객체 목록을 리턴하는 경우 응답 항상 응답에 리소스의 총 갯수를 포함해야 합니다. 이를 위해 total 속성을 사용할 수 있습니다.

 

Good:

{
  users: [ 
     ...
  ],
  total: 34
}

 

Bad:

{
  users: [ 
     ...
  ]
}

 

 

13. Accept limit and offset Parameters

---

GET 작업에서는 항상 limit, offset 파라미터를 받습니다.

 

Good:

GET /shops?offset=5&limit=5

이는 프론트 엔드에서의 페이지 네이션에 필요하기 때문입니다.

 

 

14. Take fields Query Parameter

---

반환되는 데이터의 양도 고려해야 합니다. API에서 필수 필드만 노출하도록 매개변수를 추가합니다.

다음 예시는 샵의 id, 이름, 주소, 연락처만 반환하는 API 입니다.

 

Good:

GET /shops?fields=id,name,address,contact

또한 경우에 따라 응답 크기를 줄이는 데 도움이 됩니다.

 

 

15. Don't Pass Authentication Tokens in URL

---

종종 URL이 기록되고 인증 토큰도 불필요하게 기록되기 때문에 이는 매우 나쁜 방법입니다.

URL 대신 Header와 함께 전달하세요.

 

Good:

Authorization: Bearer xxxxxx, Extra yyyyy

 

Bad:

GET /shops/123?token=some_kind_of_authenticaiton_token

 

 

16. Validate the Content-Type

---

서버는 Content-Type을 확신해서는 안됩니다. 예를 들어 application/x-www-form-urlencoded 에 대해 수락한다면, 공격자는 양식을 만들고 간단한 POST 요청을 통해 트리거를 할 수 있습니다.

 

 

17. Use HTTP Methods for CRUD Functions

---

HTTP 메소드는 CRUD 기능을 설명하기 위한 목적으로 사용됩니다.

•  GET : 자원의 표현을 검색합니다.
•  POST : 새로운 자원과 하위 자원을 생성합니다.
•  PUT : 기존 자원을 업데이트합니다.
•  PATCH : 기존 자원을 업데이트합니다. 제공된 필드만 업데이트하며 나머지 필드는 그대로 둡니다.
•  DELETE : 기존 리소스를 삭제합니다.

 

 

18. Use the Relation in the URL For Nested Resources

---

중첩 리소스에 대한 URL 관계 사용에 대한 몇몇 실용적인 예는 다음과 같습니다.

•  GET /shops/2/products : 2번 Shop의 모든 제품 리스트를 조회합니다.
•  GET /shops/2/products/31 : 2번 Shop에 속한 31번 상품의 정보를 조회합니다.
•  DELETE /shops/2/products/31 : 2번 Shop에 속한 31번 상품을 삭제합니다.
•  PUT /shops/2/products/31 : 2번 Shop에 속한 31번 상품을 업데이트합니다. 
•  POST /shops : 새 Shop을 만들고 생성된 새 상점의 세부 정보를 반환해야 합니다. 

 

 

19. CORS

---

모든 공개 API에 대해 CORS(Cross-Origin Resource Sharing) 헤더를 지원합니다.

CORS 허용 출처 "*"을 지원하고, 유효한 OAuth tokens을 통해 권한 부여를 하는 것을 고려하세요.

 

 

20. Security

---

모든 엔드포인트, 리소스 및 서비스에서 HTTPS(TLS-encrypted)를 시행합니다.

모든 콜백 URL, 푸시 알림, 엔드포인트, 웹훅에 대해 HTTPS를 시행하고 요구합니다.

 

 

21. Errors

---

 

오류 및 서비스 오류는 클라이언트가 유효하지 않거나 서비스에 대해 잘못된 요청을 하거나, 잘못된 데이터를 서비스에 전달하고 서비스가 요청을 거부할 때 발생합니다.

예를 들어 잘못된 인증 자격 증명, 잘못된 매개변수, 알 수 없는 버전 ID 등이 있습니다.

• 하나 이상의 서비스 오류로 인해 클라이언트 요청을 거부할 때  4xx  HTTP 오류 코드를 반환합니다.
• 모든 속성을 처리한 후 단일 응답으로 여러 유효성 검사를 반환하는 것을 고려하세요.

 

 

22. Golden Rules

---

API 디자엔애 대해 확신이 서지 않는 경우 다음과 같은  Golden Rules 는 올바른 결정을 내리는 데 도움이 될 수 있습니다.

• 플랫은 중첩보다 낫습니다.
• 단순한 것이 복잡한 것보다 낫습니다.
• 숫자보다 문자열이 좋습니다.
• 일관성은 사용자 정의보다 낫습니다.

 

 

정리

---

원문을 기반으로 API를 디자인하는 22가지의 Best Practices에 대해 번역글을 작성해보았습니다.

REST API 설계를 고려하다 보면 포스팅에 존재하는 대부분의 내용들에 대해 한 번씩 고려할만한 사항들입니다.

정리하면서 흥미로웠던 번호는 6 7 8 12 14 16 입니다.

• 6. Use Verbs for Non-Resource URL
• 7. Use camelCase for JSON property
• 8. Monitoring
• 12. Include Total Number of Resources in Your Response
• 14. Take fields Query Parameter
• 16. Validate the Content-Type

리퀘스트, 리스폰스가 JSON 형식이라면 속성 값은 카멜케이스를 사용하라는 점, 헬스체크나 버전관리, 매트릭 등에 대한 API 제공, 응답 객체의 총 갯수를 같이 반환하는 점, Content-Type에 대한 유효성 검사 등 다양한 방법에 대해서도 배울 수 있었습니다.