원본 링크

번역이 다소 미흡할 수 있습니다.
양해 부탁드립니다.

---

Photo by Andrea Piacquadio from Pexels

모든 것을 추측해야만 하는 끔찍한 API에 절망한 적이 있습니까?

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

오늘 우리는 따라야 할 몇 가지 best practices 대해 이야기하겠습니다.

---

몇 가지 용어 정리

Resource Oriented Design 에서 이야기하는 모든 API 디자인은 3가지 핵심 개념으로 구성됩니다.

• Resource : Resource는 데이터 조각입니다.
  Example : a User

• Collection : Resource 그룹을 Collection 이라고 합니다.
  Example : A list of users

• URL : Resource 또는 Collection의 위치를 식별합니다.
  Example: /user

---

1. URL에는 kebab-case 사용

예를 들어, 주문 리스트를 얻으려면

Bad

/systemOrders

또는

/system_orders

Good

/system-orders

---

2. 파라미터에는 camelCase 사용

예를 들어, 특정 상점에서 상품을 얻으려는 경우

Bad

/system-orders/{order_id}

또는

/system-orders/{OrderId}

Good

/system-orders/{orderId}

---

3. Collection은 복수 명칭을 사용

시스템의 모든 사용자를 얻으려면,

Bad

GET /user

또는

GET /User

Good

GET /users

---

4. URL은 Collection으로 시작하고 식별자로 끝납니다.

개념을 단일하고 일관되게 유지하고자 할 때

Bad

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

이것은 리소스 대신 속성을 가리키기 때문에 좋지 않습니다.

Good

GET /shops/:shopId/

또는

GET /category/:categoryId

---

5. Resource URL에서 동사 금지

URL에서 의도를 표현하기 위해 동사를 사용하지 마십시오. 대신 적절한 HTTP 메서드를 사용하여 작업을 설명하십시오.

Bad

POST /updateuser/{userId}

또는

GET /getusers

Good

PUT /user/{userId}

---

6. Resource URL이 아닌 경우에 동사 사용

아무것도 리턴하지 않는 엔드포인트가 있습니다. 이 경우 동사를 사용할 수 있습니다. 예를 들어 사용자에게 경고를 다시 보내려는 경우입니다.

Good

POST /alerts/245743/resend

이것은 CRUD 작업이 아님을 명십하십시오. 오히려 이것은 시스템에서 특정 작업을 수행하는 기능으로 간주됩니다.

---

7. JSON 속성에 camelCase 사용

요청 또는 응답이 JSON 형식인 시스템의 경우, 속성의 네이밍은 camelCase 를 사용합니다.

Bad

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

Good

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

---

8. 모니터링

RESTful HTTP 서비스는 /health, /version, /metrics 엔드포인트를 구현해야 합니다.

/health

200 OK status code를 응답합니다.

/version

version number를 응답합니다.

/metrics

이 엔드포인트는 평균 응답 시간과 같은 다양한 메트릭을 제공합니다.

/debug, /status 엔드포인트를 사용하는 것도 추천되는 방법입니다.

---

9. 리소스 이름으로 table_name을 사용하지 마십시오.

테이블 이름을 리소스 이름으로 사용하지 마십시오. 장기적으로 이런 종류의 게으름은 해로울 수 있습니다.

Bad: product_order

Good: product-orders

이는 기본 아키텍처를 노출하는 것이 목적이 아니기 때문입니다.

---

10. API 디자인 도구 사용

API 디자인의 문서화를 위한 좋은 도구가 있습니다.

• API Blueprint
• Swagger

Swagger

훌륭하고 상세한 문서로 API 사용자에게 훌륭한 사용자 경험을 제공합니다.

---

11. 버전으로 단순 서수 사용

항상 API 버전 관리를 사용하고 가장 높은 범위를 갖도록 왼쪽 끝에 표시합니다. 버전은 이 형식으로 작성해야 합니다. v1, v2 등

Good

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

API를 외부 사용자가 사용하는 경우 엔드포인트를 변경하면 해당 기능이 손상 될 수 있으므로 항상 API에서 버전 관리를 사용하십시오.

---

12. 응답에 총 리소스 수 포함

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

Bad

{
  users: [
     ...
  ]
}

Good

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

---

13. limit 및 offset 파라미터

GET 요청 시 항상 limit및 offset 파라미터를 수용하도록 하십시오.

Good

GET /shops?offset=5&limit=5

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

---

14. field 쿼리의 값만 가져 오기

응답하는 데이터의 양도 고려해야합니다. fields API에서 필수 필드 만 표시 하는 파라미터를 추가하십시오.

Example

상점의 이름, 주소, 연락처만 받길 원하는 경우

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

경우에 따라 response size를 줄이는 데 도움이됩니다.

15. URL에 인증 토큰을 전달하지 마십시오

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

Bad

GET /shops/123?token=some_kind_of_authenticaiton_token

Good

대신 헤더를 통해 전달하십시오.

Authorization: Bearer xxxxxx, Extra yyyyy

인증 토큰은 수명이 짧아야합니다.

16. Content-Type 유효성 검사

서버는 content-type 을 추측하지 않아야합니다. 예를 들어, application/x-www-form-urlencoded 을 수락하면 공격자가 양식을 만들고 간단한 POST 요청을 트리거 할 수 있습니다.

항상 content-type을 검사하고 기본값을 사용하려는 경우에는 content-type: application/json을 사용합니다.

17. CRUD 함수에 HTTP 메서드 사용

HTTP 메서드는 CRUD 기능을 설명하는 용도로 사용됩니다.

GET : resource를 검색합니다.

POST : 새로운 resource 및 하위 resource를 생성합니다.

PUT : resource를 업데이트합니다.

PATCH : resource를 업데이트합니다. 제공된 필드만 업데이트하고 나머지는 그대로 둡니다.

DELETE : resource를 삭제합니다.

18. URL에서 nested resource의 관계

몇 가지 실용적인 예는 다음과 같습니다.

• GET /shops/2/products : shop 2에서 모든 제품 목록을 가져옵니다.

• GET /shops/2/products/31 : shop 2에 속한 31번 product의 상세 정보를 확인합니다.

• DELETE /shops/2/products/31, shop 2에 속한 31번 product를 삭제합니다.

• PUT /shops/2/products/31, 컬렉션이 아닌 리소스 URL에서만 PUT 사용, 31번 product의 정보를 업데이트 합니다.

• POST /shops, 새로운 shop을 만들고, 생성된 shop의 세부 정보를 응답합니다. Collection URL에 POST를 사용합니다.

---

19. CORS

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

CORS 허용 출처 "*" 를 지원하고 유효한 OAuth 토큰을 통해 승인 하는 것을 고려하십시오.

사용자 자격 증명을 원본 유효성 검사와 결합하지 마십시오.

20. 보안

모든 엔드포인트, 리소스 및 서비스에 HTTPS (TLS 암호화)를 적용합니다.

모든 콜백 URL, 푸시 알림 엔드 포인트 및 webhooks에 HTTPS를 적용하고 요구합니다.

21. 에러

에러, 좀 더 구체적으로 서비스 에러는, 클라이언트가 유효하지 않거나 잘못된 요청이나 데이터를 서비스에 전달하고 서비스가 요청을 거부 할 때 발생합니다.

예를 들면 잘못된 자격 증명, 잘못된 파라미터, 알 수 없는 version ID 등이 있습니다.

• 하나 이상의 서비스 오류로 인해 클라이언트 요청을 거부 할 때 4xx HTTP 오류 코드를 반환 합니다.

• 모든 속성을 처리 한 다음 단일 응답으로 여러 유효성 검사 문제를 응답하는 것을 고려하십시오.

22. 황금률

API 형식을 결정하는데 의심이 되는 경우, 아래의 황금률이 올바른 결정을 내리는 데 도움이 될 수 있습니다.

• flat이 nested보다 낫습니다.
• 단순한 것이 복잡한 것보다 낫습니다.
• 문자열은 숫자보다 낫습니다.
• 일관성이 커스터마이징보다 낫습니다.

그게 다입니다. — 여기까지 성공했다면 축하합니다! 한두 가지 배웠기를 바랍니다.

좋은 하루 보내세요!