올바른 REST API 디자인 사례

API란?

 

728x90

API

응용 프로그래밍 인터페이스 또는 다양한 소프트웨어 서비스 간의 통신 채널의미한다. 즉, 프론트엔드, 백엔드 개발자 모두에게 중요한 개발 요소이다. 요청과 응답을 전송하는 애플리케이션을 각각 클라이언트와 서버라고 한다.

 

API는 시스템 간의 표준 통신 방법이다. 따라서 향후 문제를 방지하려면 REST API를 올바르게 구축하는 것이 중요하다. 즉, API는 작업하기 쉽고 간결하며 오용하기 어려워야 한다.

 

API 프로토콜 타입

• REST : API의 프론트엔드와 백엔드를 분리하고 개발 및 구현에 상당한 유연성을 제공하는 클라이언트 / 서버 접근 방식을 사용한다.
• RPC : 여러 매개변수를 보내고 결과를 받는 방식을 사용한다.
• SOAP : HTTP, SMTP, TCP 등 인터넷에서 발견되는 광범위한 통신 프로토콜을 지원한다.
• WebScoket : 지속적인 연결을 통해 브라우저와 서버 간에 데이터를 교환하는 방법을 제공한다.

 

잘 정의된 API

1. 동사 대신 명사 사용

엔드포인트 경로에는 동사를 사용하면 안된다. 경로 이름에는 우리가 엑세스하거나 변경하는 엔드포인트가 속한 개체를 식별하는 명사가 포함되어야 한다.

/getAllClients -> /clients

 

2. 복수형 명사를 사용

모든 리소스 명사에는 복수형을 사용한다.

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

 

3. 일관성을 유지

일관성이 있는 것은 예측이 가능하다는 뜻이다. 즉, 하나의 리소스에 대해 동일한 사례, 모든 엔드포인트에 대해 동일한 인증방법, 동일한 헤더, 동일한 상태코드를 사용

 

4. 단순함

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

/users = 모든 유저
/users/123 = 특정 유저

 

5. 사용자의 적절한 코드 상태

HTTP status 코드는 많이만 일반적으로 일부만 사용한다. 즉 API 전체에서 동일한 결과에 대해 동일한 상태 코드를 사용하는 것이다.

• 200(성공) : 클라이언트가 요청한 동작을 수신하여 이해하였고 승낙하였으며 성공적으로 처리
• 201(생성됨) : 요청이 처리되어서 새로운 리소스가 생성되었다.
• 202(허용됨) : 요청은 접수하였지만, 처리가 완료되지 않았다.

더 많은 status 코드를 보고 싶다면 여기를 참고하자.

 

6. 일반 텍스트를 반환하지 않기

REST API는 데이터 전송을 위한 표준이기 때문에 요청 페이로드에 대해 JSON을 수락하고 JSON으로 응답한다. 

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

 

7. 적절한 오류 처리를 수행

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

 

8. 좋은 보안 관행

클라이언트와 서버 간의 모든 통신이 보호되기를 원한다. 즉, 예외 없이 항상 SSL/TLS를 사용해야 한다. 만료 날짜가 있는 사용자 정의 HTTP 헤더를 사용하여 전달되어야 하는 API키를 통해 인증허용 한다.

 

9. 페이지 매김 사용

API가 많은 데이터를 반환해야 하는 경우는 page, page_size를 사용

/products?page=10&page_size=20

 

10. 버전 관리

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

/products/v1/4

 

 

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