API 목록 응답에서 정렬 기준을 명시하자

정렬이 명시되지 않으면 문제다

API를 설계할 때 자주 간과하는 부분이 있다. 목록을 반환할 때 정렬 순서를 명시하지 않는 것이다.

GET /api/posts
{
  "data": [
    { "id": 1, "title": "Post A", "created": "2026-06-01" },
    { "id": 2, "title": "Post B", "created": "2026-06-02" },
    { "id": 3, "title": "Post C", "created": "2026-06-03" }
  ]
}

이 목록의 순서가 뭘 기준으로 정렬된 건지 명시되지 않았다. 생성 날짜? ID? 제목의 알파벳순?

문서에 명시하기

API 문서에 명확히 써야 한다:

GET /posts
- 응답은 생성 날짜(created) 기준 최신순 정렬
- 같은 날짜면 ID 역순

또는 응답 자체에 정보를 포함시키기:

{
  "data": [...],
  "meta": {
    "sortBy": "created",
    "sortOrder": "desc"
  }
}

쿼리 파라미터로 제어 가능하게 하기

더 나은 방법은 클라이언트가 정렬을 지정하도록 하는 것이다:

GET /api/posts?sortBy=created&order=desc
GET /api/posts?sortBy=title&order=asc

백엔드는 이 파라미터를 처리하고:

const sortBy = req.query.sortBy || 'created';
const order = req.query.order || 'desc';
const posts = db.posts.sort({ [sortBy]: order === 'desc' ? -1 : 1 });

기본값 정하기

명시하지 않으면 어떤 순서가 기본인지도 중요하다.

일반적인 관례:

• 시간 기반 데이터: 최신순(역순)
• 이름 기반 데이터: 알파벳순(정순)
• 인덱스: ID 정순

내 실수

과거에 쓴 API에서는 정렬 기준을 명시하지 않았다가 클라이언트가 "왜 순서가 자꾸 바뀌나요?"라고 물었다. 데이터베이스 인덱스 최적화 후 순서가 바뀌었던 거였다. 그 이후로는 항상 명시한다.