📋 REST API에 대하여

REST API

• 오늘날 사용 가능한 가장 일반적인 웹 서비스 유형 중 하나
• 브라우저 앱을 포함한 다양한 클라이언트가 REST API를 통해 서버와 통신
• stateless 통신 및 캐시 가능한 데이터같은 특정 아키텍처 제약 조건을 준수하는 애플리케이션 프로그래밍 인터페이스
• 프로토콜이나 표준이 아님
• 여러 통신 프로토콜을 통해 액세스 할 수 있지만 일반적으로 HTTPS를 통해 호출됨

REST API 구성

REST : Representational State Transfer라는 용어의 약자

• 자원 : URI
• 행위 : HTTP METHOD
• 표현

REST 의 특징

• Uniform Interface
• Stateless
• Caching
• Client-Server
• Hierarchical system
• Code on demand

REST API 디자인 가이드

URI는 자원을 표현하는데 집중하고 행위에 대한 정의는 HTTP 메소드를 통해 나타낸다.

• URI는 정보의 자원을 표현해야 한다 : 리소스명은 동사보다 명사를 사용한다.
• 자원에 대한 행위는 HTTP 메소드로 표현한다.

URI 설계 시 주의 사항

• 슬래시 (/)는 계층 관계를 나타내는 데 사용한다.
• 마지막 문자로 슬래시를 포함하지 않는다.
• 긴 URL 경로의 가독성을 높이기 위해서 하이픈(-)을 사용한다.
• 밑줄(_)은 URL에 사용하지 않는다.
• URL은 소문자를 사용한다.
• 파일 확장자는 URI에 포함시키지 않는다.

리소스 간의 관계를 표현하는 방법

• /리소스명/리소스 ID/관계가 있는 다른 리소스명
• 관계명이 복잡할 경우 서브 리소스에 명시적으로 표현한다. ex) GET : /users/{userid}/likes/devices

Colllection과 Document

• Colllection : 문서들의 집합, 객체들의 집합. 복수로 사용한다.
• Document : 단순한 문서 혹은 한 객체

/games/{id}/score
/games/{id}/load
/games/{id}/move

HTTP 응답 상태 코드

200

• 200 : 클라이언트의 요청을 정상적으로 수행함
• 201 : 클라이언트가 어떠한 리소스 생성을 요청, 해당 리소스가 성공적으로 생성됨(POST를 통한 리소스 생성 작업 시)

400

• 400 : 클라이언트의 요청이 부적절 할 경우 사용하는 응답 코드
• 401 : 클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 때 사용하는 응답 코드
• 403 : 유저 인증상태와 관계 없이 응답하고 싶지 않은 리소스를 클라이언트가 요청했을 때 사용하는 응답 코드
• 404 : 서버가 요청한 페이지(Resource)를 찾을 수 없을 경우 사용하는 응답 코드

ect

• 301 : 클라이언트가 요청한 리소스에 대한 URI가 변경 되었을 때 사용하는 응답 코드
• 500 : 서버에 문제가 있을 경우 사용하는 응답 코드

참고

REST API 제대로 알고 사용하기 : NHN Cloud Meetup

❓ 잘못된 데이터로 요청하여 DB오류가 발생할 시 어떤 상태코드를 돌려주어야 하나?

서버에서 SQLException이 발생할 경우 이를 클라이언트에 알려야 하나,
또는 어떤 상태코드를 주어야 하나에 대해 이야기해보았다.

일단 결론은 잘못된 데이터로 결과 값을 가져올 수 없는 경우, 서버에러가 아닌 때에 따라 적절한 상태코드를 돌려준다.
웹 API 디자인을 참고하였다.

POST - 잘못된 데이터 추가 요청일 경우 400

PUT - 데이터 수정이 실패한 경우 409

서버에서 처리하고 상태코드를 보낼 때 정해진 약속을 생각해보고 적절한 상태코드를 보내어 클라이언트가 요청에 대한 결과를 정확히 알 수 있도록 하자!

REST API 설계를위한 모범 사례

2021-06-09 추가

JSON으로 accept와 respond

• JSON은 데이터 전송을위한 표준
• JS의 Fetch API 등은 JSON을 인코딩 및 디코딩하는 내장 메서드가 있음
• JSON으로 응답 할 때 클라이언트가이를 해석하도록 하려면 Content-Type: application/json 를 응답 헤더로 설정해야함

동사대신 명사 사용

• HTTP 요청 메서드에 이미 동사가 있기 때문
• 동사가있는 것은 새로운 정보를 전달하지 않기 때문에 불필요하게 길어짐

논리적 중첩 사용

• 한 개체가 다른 개체를 포함 할 수있는 경우이를 반영
• 여기서 데이터베이스와 관계없이 디자인하기
  • 실제로 공격자에세 불필요한 정보를 제공하지 않도록 데이터베이스 구조를 미러링 하지 않는 것이 좋음

표준 오류 코드 반환

• 오류 코드는 관리자가 문제를 해결할 수있는 충분한 정보를 갖도록 메시지가 함께 있어야 함
• 하지만 공격자가 이를 악용할 수 있음

일반적인 HTTP 오류 상태코드

• 400 : 클라이언트 측 입력이 유효성 검사에 실패
• 401 : 사용자가 리소스에 액세스 할 수있는 권한이 없음
• 403 : 사용자가 인증되었지만 리소스에 액세스 할 수 없음
• 404 : 리소스를 찾을 수 없음
• 500 : 일반 서버 오류. 명시적으로 던져서는 안됨
• 503 : 서버 측에서 예기치 않은 일이 발생했음 (서버 과부하, 시스템의 일부 오류 등)

보안

• SSL 인증서는 서버에로드하기가 그리 어렵지 않으며 비용이 무료이거나 매우 낮음
• 때문에 SSL위에서 구동되는 HTTPS를 이용하자
• 사용자들이 서로의 정보에 액세스 할 수 없도록 막아야 함

성능 향상을 위한 데이터 캐싱

• 사용자가 요청한 일부 데이터를 검색 할 때마다 데이터를 가져 오기 위해 데이터베이스를 조회하는 대신
• 로컬 메모리 캐시에서 데이터를 반환하는 캐싱을 추가 할 수 있음
• 덕분에 사용자가 데이터를 더 빨리 얻을 수 있음
• 하지만 사용자가 얻는 데이터는 오래되었을 수 있음 (문제)
• Redis, 인메모리 캐싱 등을 사용할 수 있음
• 요구사항이 변경되면 데이터가 캐싱되는 방식을 변경할 수 있음
• 캐싱을 사용하는 경우 Cache-Control헤더 에도 정보를 포함해야함

API 버전 관리

• API에 변경사항이 생겨 이를 반영하는 경우 다른 버전의 API가 있어야 함
• v1 엔드 포인트는 변경을 원하지 않는 사람들을 위해 활성 상태를 유지
• v2는 업그레이드 할 준비가 된 사람들에게 서비스를 제공
• 버전은 일반적으로 수행 /v1/, /v2/등 API 경로의 시작 부분에 추가

참고

• REST API 설계를위한 모범 사례

➕ API 설계에 대한 정해진 규약?

• API를 활용하는 사람들과 충분한 논의 후 결정하기
• 많은 사람들의 공감
• RFC 문서나 많은 사람들 사용하는 API설계 활용