적을수록 좋다. 모든 물건은 맞는 자리에 있어야 한다.
API의 데이터, 피드백, 목표를 구성하고 크기를 정하는 것은 API를 만드는데 매우 중요한 역할이다.
API 구조화
논리적으로 그룹화되고 정렬된 경우, 원하는 요소를 쉽게 찾아내고 그 목적도 이해하기 쉽게 해준다.
데이터 구조화하기
-
데이터 그룹화를 통해 데이터의 연관성을 표현
- 관련된 속성들은 서로 가깝게 배치
- 일반적인 접두사를 사용하고 필요하다면 하위 구조를 만듦
-
데이터를 중요도에 따라 정렬하여 가독성을 향상
- 데이터 그룹은 중요한 순서부터 덜 중요한 순서로 배치
| 무작위로 배치된 속성들 | 정렬된 속성들 |
|---|---|
 |  |
피드백 구조화하기
- API 상태 코드
- 그룹화하고 정렬한 에러들
목표 구조화하기
API의 목표는 가상이든 실제 물리적으로든 조직화하여 나눌 수 있다.
-
openAPI 명세에서 태그를 이용해 그룹화된 목표들
-
목표들을 기능적인 관점에서 그룹화
- REST API를 디자인할때, URL 경로가 바로 목표를 대변한다고 착각하면 안 된다.
- 반드시 각 목표의 기능적인 측면에 집중
-
정렬된 태그 정의를 추가해 목표 그룹을 정렬
- tags의 정의를 최상위 레벨에 추가하여 카테고리를 정렬할 수 있다.
-
OpenAPI 명세 문서 상에서 목표를 정렬하기
- 명세 문서 자체에서만 중요도에 따라 목표를 정렬해서 표시하기
- HTTP 메서드의 순서도 모든 리소스 간에 순서가 동일해야한다. (GET, POST, DELETE 순)
API 목표를 가상 또는 물리적으로 구조화하면 컨슈머가 API를 이해하는 데 큰 도움이 된다.
API 사이징
객체가 지나치게 많은 기능을 제공하거나 너무 많은 제어나, 너무 많은 정보를 제공하면 일반적으로 사용성이 심각하게 떨어져서 사용할 수 없다.
이러한 객체들은 지나치게 비대하고, 불편한데다가, 사용자를 겁에 질리게 만드는 경향이 있다.
데이터 세분화 선택하기
| 컨텍스트 | 속성의 개수 | 최대 깊이 |
|---|---|---|
| 입력 | 가능한 최소 | 얕게(추천: 최대 3단계) |
| 출력 | 기능적으로 관련된 수준으로 | 기능적으로 관련된 수준으로(추천: 최대 3 단계) |
API에서 데이터 구조에 담겨 반환될 속성의 개수는 기능적 연관성에 따라 달라진다.
제공되는 속성들은 컨텍스트 상에서 기능적으로 적절해야 한다.
설령 이것들이 적절하다고 판단되었을지라도, 많은 수의 속성을 지니는 건 사용성을 증가시키는데 아무런 도움도 되지 않는다.
보통 속성이 20개가 넘어가는 순간 데이터를 구조화하거나 속성을 하나씩 검토해보는 것 보다는 자신만의 규칙을 자신의 도메인 바탕으로 정의하자.
입력과 출력 모두 3단계를 넘는 깊이를 쓰는 것은 추천하지 않는다.
만약 그 이상의 깊이에 도달하게 된다면, 원시 데이터를 다루거나, 코딩하거나 거기에 대한 문서를 읽는 행위마저도 복잡해진다.
데이터를 구조화하는 것은 여러분의 API를 쉽게 만드는 데 도움이 되므로 균형을 맞춰야 한다.
데이터 세분화란 기능적 관점의 세분화일 뿐 제공하는 데이터 수는 중요하지 않다. 목표 또한 세분화를 고려해야 한다.
목표 세분화 선택하기
API 목표를 식별하거나 프로그래밍 인터페이스를 디자인하는 동안 목표에 따라 API가 그룹화됐더라도, 여전히 기능적으로 유용하고 독립적인 단위로 나눌 수 있다.
요약
- 데이터의 이름에 패턴을 이용하거나 관련 있는데이터들끼리 그룹화하고 정렬하여 데이터를 구조화
- 피드백을 카테고리화하고 중요에 따라 정렬
- 표현 수준이 아니라 기능 수준으로 목표를 그룹화
- API 명세 포맷의 기능( OpenAPI 태그)을 활용하거나 네이밍 패턴(REST API의 URL 접두사)을 사용하면 좋다
- 모든 걸 다 하는 목표는 좋지 않다.
- 데이터 구좌와 목표, 심지어 API 까지 모두 기능적으로 유의미한 수준에서 쪼갤 수 있다면 더 작게 쪼개자
