REST API 설계 및 사용 시 참고 사항

🍎 글의 시작점

- 서버 애플리케이션을 개발하며 클라이언트와의 통신을 위해 REST API 스펙을 설계할 때, 도움이 될 만한 팁과 방법을 정리한 글입니다.

---

🍏 참고 사항

- API는 기본적으로 Client 곳곳에서 사용할 걸 가정하고 만들어야 하므로, 가급적 범용적으로 만들고 갖다 쓰는 쪽에서 응용해서 사용해야 합니다.

- 매우 제한적인 이유로 (퍼포먼스라든지) 전용 API를 만들어서 해결해야 하는 경우도 있지만 그건 원칙을 어긋나는 경우라고 생각합니다.

• 제한적인 상황의 전용 API의 예시
  • 임시로 백 투 백으로 서버 데이터를 동기화하는 API의 경우 제한적으로 만들어 사용합니다. 이러한 API는 특정 상황이나 기간에만 필요하고, 시스템이 안정화되거나 이전이 완료되면 사용이 중단되는 경우가 많습니다.

- API 설계에 있어 정체성, 그리고 제공하거나 제공받는 각 필드의 정체성은 명확해야 합니다. 그리고 좋은 API는 거기에 덧붙여서 확장이 가능하도록 설계합니다.

• 정체성이 명확한 API란❓ API가 갖고 있는 의미가 애매모호하지 않고 명확한 것이라고 생각합니다. 예를 들어 "시험지"를 처리해야 하는 요구사항이 있다고 가정해 보겠습니다. 그리고 세부 요구사항으로는 간단히 두 개로 정의가 된 상황입니다.
  1. 시험지 ID에 따라 매 단계별 사용자의 응답을 저장한다.
  2. 시험의 모든 단계가 끝난 후 결과를 사용자에게 보여준다.
• 정체성에 대해서 크게 생각하지 않았을 땐 아래와 같이 ID값으로 정의하고 처리해 마지막 단계가 끝난 상황에서 결과값도 얻게 될 것이니 하나의 EndPoint만 존재하면 된다고 생각했습니다.

POST /api/exam/{examId}

• 그러나, "사용자가 경험한 시험들의 결과를 보여준다"라는 요구사항을 받았을 때 위의 POST EndPoint 만으로 해결할 수 없었습니다. 다시 말해 정체성을 생각하지 않고 API를 설계했기 때문에 문제를 마주하게 된 것입니다.

- 클라이언트의 특수한 상황을 이유로 서버 API의 설계를 바꾸지 않는 것이 맞고, 물론 클라이언트 입장에서는 그 입장이 특수한지 일반적인지 알 수 없을 수도 있는데, 필요한 속성이 설계에 위배하지 않도록 설계를 수정할 수도 있습니다만, 기본적으로 api의 설계는 클라이언트의 상황을 고려하지 않고 설계되어야 하는 게 맞다고 봅니다.

 

- REST API에서 GET 메쏘드의 경우 기본적으로 조회용으로, POST는 변경용으로 사용하는 경우가 많지만, 항상 그런 건 아닙니다.

 

- URL 캐시를 위해서 일부러 POST를 GET으로 바꿔서 사용하기도 하고, 보안에 민감한 데이터를 브라우저 히스토리나, ISP 캐시 등에 노

출시키지 않기 위해서 일부러 전부 다 POST로 던지기도 합니다.

 

- 과거에는 GET에 붙는 파라메터 사이즈가 2048 bytes를 넘지 못했기 때문에 조회라 하더라도 POST로 던지는 경우도 많았고, 매우 특수하게 웹서버 로깅 수집을 목적으로 변경 데이터를 GET으로 던지기도 했습니다.

---

❓ 그렇다면 이 글을 통해 무엇을 이야기하고 싶은건가요?

- 아이러니하게도 API를 설계할 때 정해진 Form이라는 것이 없다는 것을 이야기하고 싶은 것입니다. 그러나, 개발 상황과 자원에 맞춰 정체성을 생각하고 API를 설계한다면 범용적으로 사용할 수 있는 REST API를 만들 수 있다고 생각합니다.