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


REST API Design Best Practices

Medium

REST API Design Best Practices

다음 내용이 궁금하다면?

또는

이미 회원이신가요?

2024년 2월 13일 오전 7:55

 • 

저장 552조회 14,567

댓글 0