올바른 REST API 디자인 사례 : API 설계 가이드 🥰

API에는 다양한 타입이 있죠. API는 프론트엔드, 백엔드 개발자 모두에게 중요한 개발 요소입니다. API를 통해 서버와 클라이언트가 소통하듯이 좋은 API 설계는 각 파트 간 개발자들의 소통에도 중요합니다. 그 중 REST API 설계 사례를 통해 어떻게 API를 구현하는 게 좋은지 알아보도록 하겠습니다!

1. API란?

   • API(Application Programming Interface)는 다양한 소프트웨어 간의 커뮤니케이션 채널입니다.

   • API 요청을 전송하는 클라이언트 <-> API 응답을 전송하는 서버
     
     

2. API 프로토콜의 타입들

   • REST : API의 프론트엔드와 백엔드를 분리하고, 개발과 구현에 유연성을 제공하는 클라이언트 <-> 서버 접근 방식 사용

   • RPC : 여러 매개 변수를 보내고 결과를 받는 방식을 사용

   • SOAP : HTTP, SMTP, TCP 등 인터넷의 광범위한 통신 프로토콜을 지원

   • WebSocket : 지속적 연결을 통해 브라우저와 서버 간 데이터를 교환하는 방법을 지원
     
     

3. 잘 정의된 API란 무엇인가? 😮

   • 동사 대신 명사 사용하기

     • 엔드포인트 경로 이름에는 개체를 식별할 수 있는 명사를 사용하기

       /getAllClients ->/clients
       
       

   • 복수형 명사 사용하기

     • 리소스 명사에는 복수형을 사용하기

       /employee/:id/ -> /employees/:id/
       
       

   • 일관성 유지하기

     • 하나의 리소스에 대해 동일한 사례, 모든 엔드포인트에 대한 동일한 인증 방법, 동일한 헤더, 동일한 상태 코드를 사용하기
       
       

   • 심플하게 유지하기

     • 모든 엔드 포인트의 이름을 리소스 지향적으로 설정하기

       /users 모든 유저

       /users/124 특정 유저
       
       

   • 적절한 상태 코드 만들기

     • HTTP 상태 코드를 너무 많이 사용하지 말고 API 전체에서 동일한 결과에 대해 동일한 상태 코드 사용하기

       200 for general success

       201 for successful creation

       202 for a successful request

       204 for no content .....
       
       

   • 일반 텍스트(Plain text)를 반환하지 않기

     • JSON 형식의 문자열로 본문을 반환하는 것만으로는 충분하지 않음. Content-Type 헤더를 application/JSON으로 지정해야 함
       
       

   • 적절한 오류 처리 수행하기

     • 오류를 적절히 처리하고 무슨 일이 일어 났는지 나타내는 응답코드(400 ~ 5xx)를 반환하기. 상태코드와 함께 응답 본문에 일부 세부 정보를 반환해야 함
       
       

   • 좋은 보안 관행을 갖추기

     • 예외 없이 SSL/TLS를 사용하기. 만료 날짜가 있는 사용자 정의 HTTP 헤더를 사용하여 전달 되어야 하는 API키 인증을 허용하기
       
       

   • 페이지 매기기

     • API가 많은 페이지를 반환하는 경우 page, page_size를 삽입하기

       /products?page=10&page_size=20
       
       

   • 버전 관리하기

     • API 사용자가 다를 수 있으므로 첫 번째 버전부터 API 버전을 지정하기

       /products/v1/4

위의 글은 아래 Medium 글을 번역해 가져온 것인데요.

더 자세한 설명을 원하신다면 아래의 링크를 참고해 보세요!

https://medium.com/@techworldwithmilan/rest-api-design-best-practices-2eb5e749d428