인프라
REST API에 대하여
newwisdom
2021. 8. 6. 12:14
반응형
2021-04-21글
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 경로의 시작 부분에 추가
참고
➕ API 설계에 대한 정해진 규약?
- API를 활용하는 사람들과 충분한 논의 후 결정하기
- 많은 사람들의 공감
- RFC 문서나 많은 사람들 사용하는 API설계 활용
반응형