[4주차 토론] 팀별 토론

[choyeongju]

✅ 좋은 명세서는 무엇이고, 클라이언트에게 어떤 명세서를 주어야할까?

1️⃣ 일관된 요청 형식과 응답 형식

[요청 형식의 통일]

API 요청할 때 사용하는 데이터 형식을 application/json 으로 통일하거나 하는 등..

[응답 형식의 통일]

💬 message 필드가 꼭 필요할까? 에 대한 고민 …

🐰 나는 필요하다고 생각한다! 클라이언트 입장에서 생각해 보았을 때, message 로 어떤 이유 때문에 error 가 발생했는지 빠르게 파악할 수 있는 경우가 많을 것이라 생각한다.
만약 message 로 간략하게 예외의 이유를 알려준다면, 클라이언트의 실수로 인해 발생한 에러라면 빠르게 실수의 이유를 파악하고 서버 측과 커뮤니케이션하는 불필요한 시간 소모 없이 처리할 수 있을 것이라 생각하기 때문이다.

 

🥕 But, 너무 자세한 에러 message 를 제공하는 것은 지양해야 할 것 같다. 악의를 가진 사용자가 이 메세지를 통해서 서비스의 약점이나 구조를 파악할 가능성이 있기 때문이다.

→ Sol 1 ) 간략한 에러 메세지를 제공하자!

→ Sol 2 ) 개발 시에는 자세한 에러 메세지를 제공하고, 개발이 완료된 후에는 간략한 메세지로 변경하거나, 메세지 필드를 아예 없애는 것도 괜찮을 것 같다고 생각한다.

 

2️⃣ API 호출 방식이나, 응답에서의 예제 코드 포함하기

 

3️⃣ 직관적인 구성

• 담당자와 배포 여부를 확실하게 알려 줄 수 있는 명세서
• 앞 단에 보이는 정보는 최소한의 정보만 보이게 해서 직관적이게!

 

4️⃣ 명세서 세부 페이지를 열었을 때는 최대한 자세하게!

• Required = false 항목의 경우에는, 언제 해당 파라미터를 넣어 주어야 하는지 정확하게 설명해주기
• 부연 설명이 필요한 경우 함께 기재해주기

 

✅ App 과 Web 서버에서 어떤 개발적인 차이가 있을까?

 

✅ 서비스 API 와 플랫폼 API 는 무슨 차이가 있을까?