올바른 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