[Network] RESTful API 의미와 설계 규칙

Study: ComputerScience(CS)/CS: Network

[Network] RESTful API 의미와 설계 규칙

DrawingProcess 2022. 7. 7. 05:45

API (Application Programming Interface)란? (= 서버 API)

API는 한 프로그램이 다른 프로그램을 이용할 때 쓰는 인터페이스로 입출력이 데이터로 됩니다.
어떤 특정 사이트에서 특정 데이터를 공유할 경우 어떤 방식으로 요청해야 하는지 어떤 데이터를 받을 수 있는지 등의 규격을 말합니다.
프로그램에게 자신이 제공하고자 하는 데이터나 기능을 제어할 수 있는 API로 만들면, 서버와 데이터베이스에 대한 접근 권한이 있는 사람들에게만 접근성 부여할 수 있습니다.
UI (User Interface)와 비교하면 이해가 편합니다.
- UI: 일반 사용자는 버튼이나 링크, 이미지등 특정 ui를 통해 조작함으로써 시스템을 제어합니다.
- API: 개발자가 특정 프로그램에서 제공하는 규격을 이용하여 응용프로그램을 제어하고 구축합니다.

HTTP API 란?

HTTP란?

HTTP(Hyper Text Transfer Protocol): HTML(웹문서를 만들기 위한 언어) 문서를 주고 받는데 쓰이는 통신프로토콜(통신규약)이며, TCP 와 UDP 를 사용하여 통신하며 80번 포트를 사용하는 통신프로토콜(통신규약)입니다.
- HTTPS: Secure HTTP - 보안요소가 추가된 것입니다.
TCP / IP 를 이용한 응용프로토콜( 응용계층에 위치하고 있어서 )
HTTP(S) 는 연결상태를 유지하지 않는 비연결성 프로토콜(클라이언트의 이전 상태, 요청등을 기억하지 않음)
- Cookie, Session 등을 도입하여 유지(Cookie - 클라이언트, Session - 클라이언트 상태 in server)

HTTP API 란?

HTTP를 사용하여 프로그램끼리 소통하는 API를 말합니다.
흔히 보는 OPEN API, facebook API, kakao API 등의 대부분 API는 HTTP라는 통신 규칙으로 소통하는 API입니다.
그렇다면 HTTP를 사용하지 않는 것도 있나요?
- 미세먼지 측정기와 스마트 창문이 IoT 애플리케이션과 통신(소통)할 수 있는 API가 있어야 합니다.
- 이때 사용하는 소통 방법은 HTTP통신이 아닌 저사양/저전력 환경에 적합한 MQTT, CoAP프로콜을 사용해야 합니다.

HTTP Method

GET : 지정된 URL에서 리소스의 표현을 조회
POST : 지정된 URL에 신규 리소스를 생성
PUT : 지정된 URL에 리소스를 생성하거나 업데이트
PATCH : 리소스의 부분 업데이트
DELETE : 지정된 URL의 리소스를 제거

RESTful API란?

RESTful API 란?

도입
- 로이 필딩(Roy Fielding)의 2000년 박사학위 논문에서 소개되었으며,
- 로이 필딩은 HTTP의 주요 저자 중 한 사람으로 그 당시 웹(HTTP) 설계의 우수성에 비해 제대로 사용되어지지 못하는 모습에 안타까워하며 HTTP의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표했습니다.
정의
- REST?
  - REpresentational State Trasfer의 약어로 웹을 이용할 때 제약 조건들을 정의하는 소프트웨어 아키텍처 스타일입니다.
- RESTful?
  - REST API의 설계 규칙을 올바르게 지킨 시스템을 RESTful하다 말할 수 있습니다.
- RESTful API?
  - 하단의 '규약'을 바탕으로 리소스 중심으로 설계하고 기능에 맞게 HTTP Method 사용하여 설계된 API입니다.
규약
- HTTP URL/URI을 통해 자원(Resource)을 명시하고,
- HTTP Method(GET, POST, PUT, DELETE)를 통해
- 해당 자원(URL)에 대한 CRUD(Create, Read, Update, Delete)를 적용하는 것을 의미합니다.
  - 한마디로 URI로 자원을 표현하는 데에 집중하고, 자원의 상태(행위)에 대한 정의는 HTTP METHOD로 하는 것이 REST한 API를 설계하는 중심 규칙입니다.

CRUD Operation

Create : 데이터 생성(POST)
Read : 데이터 조회(GET)
Update : 데이터 수정(PUT)
Delete : 데이터 삭제(DELETE)

+ HTTP API vs RESTful API

HTTP API와 REST API는 사실 거의 같은 의미로 사용하고 있으며, 정확한 차이점으로 REST API는 HTTP 프로토콜을 따르면서 아래의 4가지 가이드 원칙을 지켜야 합니다.

자원의 식별
메세지를 통한 리소스 조작
자기서술적 메세지
애플리케이션의 상태에 대한 엔진으로서 하이퍼미디어(HATEOAS)

REST 특징: REST 아키텍처에 적용되는 6가지 제한 조건

Uniform Interface(인터페이스 일관성) :
- URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 말하며,
- 일관적인 인터페이스로 분리되어야 합니다.
Stateless(무상태) :
- 각 요청 간 클라이언트의 context, 세션과 같은 작업을 위한 상태 정보를 서버에 저장하고 관리하지 않습니다.
- 세션 정보나 쿠키정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 들어오는 요청만을 단순히 처리하면 됩니다.
- 때문에 서비스의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순해집니다.
Cacheable(캐시 처리 가능) :
- REST의 가장 큰 특징 중 하나는 HTTP라는 기존 웹표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 활용이 가능하여 HTTP가 가진 캐싱 기능이 적용 가능합니다.
  - HTTP 프로토콜 표준에서 사용하는 Last-Modified태그나 E-Tag를 이용하면 캐싱 구현이 가능합니다.
- 클라이언트는 응답을 캐싱할 수 있어야 합니다. 캐시를 통해 대량의 요청을 효율적으로 처리할 수 있습니다.
Self-descriptiveness (자체 표현 구조): Code on demand
- REST API 메시지만 보고도 이를 쉽게 이해 할 수 있는 자체 표현 구조로 되어 있으며,
- 자바 애플릿이나 자바스크립트의 제공을 통해 서버가 클라이언트를 실행시킬 수 있는 로직을 전송하여 기능을 확장시킬 수 있습니다.
Client/Server(클라이언트/서버) 구조 :
- REST 서버는 API 제공, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보)등을 직접 관리하는 구조로 각각의 역할이 확실히 구분되기 때문에 아키텍처를 단순화시키고 작은 단위로 분리할 수 있습니다.
- 따라서 클라이언트-서버의 각 파트가 독립적으로 구분되어 개발해야할 내용이 명확해지고 서로 간의 의존성을 줄입니다.
계층화 :
- REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 합니다.
- 이를 통해 클라이언트는 대상 서버에 직접 연결되어있는지, Proxy를 통해서 연결되었는지 알 수 없습니다.

REST의 장단점

장점

HTTP 프로토콜의 인프라를 그대로 사용하므로 REST API 사용을 위한 별도의 인프라를 구출할 필요가 없다.
HTTP 프로토콜의 표준을 최대한 활용하여 여러 추가적인 장점을 함께 가져갈 수 있게 해 준다.
HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.
Hypermedia API의 기본을 충실히 지키면서 범용성을 보장한다.
REST API 메시지가 의도하는 바를 명확하게 나타내므로 의도하는 바를 쉽게 파악할 수 있다.
여러 가지 서비스 디자인에서 생길 수 있는 문제를 최소화한다.
서버와 클라이언트의 역할을 명확하게 분리한다.

단점

표준이 자체가 존재하지 않아 정의가 필요하다.
사용할 수 있는 메소드가 4가지밖에 없다.
HTTP Method 형태가 제한적이다.
브라우저를 통해 테스트할 일이 많은 서비스라면 쉽게 고칠 수 있는 URL보다 Header 정보의 값을 처리해야 하므로 전문성이 요구된다.
구형 브라우저에서 호환이 되지 않아 지원해주지 못하는 동작이 많다.(익스폴로어)

REST 구성요소

REST API 구성

REST는 다음과 같은 3가지로 구성되어 있습니다.

자원(Resource) : HTTP URL
자원에 대한 행위 : HTTP Method
자원에 대한 표현(Representations)

REST API 설계 규칙 및 예시

1. 소문자를 사용한다.

❌ http://cocoon1787.tistory.com/users/Post-Comments

⭕ http://cocoon1787.tistory.com/users/post-comments

대문자는 때로 문제를 일으키는 경우가 있기 때문에 소문자로 작성합니다.

2. 언더바( _ ) 대신 하이픈( - )을 사용한다.

❌ http://cocoon1787.tistory.com/users/post_comments

⭕ http://cocoon1787.tistory.com/users/post-comments

정확한 의미나 단어 결합이 불가피한 경우, 가독성을 위해 언더바("_")가 아닌 하이픈("-")을 사용하며,
하이픈("-") 사용도 최소한으로 설계합니다.

3. 마지막에 슬래시를 포함하지 않는다.

❌ http://cocoon1787.tistory.com/users/

⭕ http://cocoon1787.tistory.com/users

슬래시("/")는 계층 관계를 나타낼 때 사용됩니다.

4. 행위를 포함하지 않는다.

❌ POST http://cocoon1787.tistory.com/users/post/1

⭕ DELETE http://cocoon1787.tistory.com/users/1

자원에 대한 행위는 HTTP Method로 표현합니다.(GET, POST, DELETE, PUT)

5. 파일 확장자는 URL에 포함시키지 않는다.

❌ http://cocoon1787.tistory.com/users/photo.jpg

⭕ GET http://cocoon1787.tistory.com/users/photo
   HTTP/1.1 Host: cocoon1787.tistory.com Accept: image/jpg

URL에 메시지 body 내용의 포맷을 나타내기 위한 파일 확장자를 적지 않습니다. 대신 Accept header를 사용합니다.

6. 자원에는 형용사/동사가 아닌 명사를 사용하며, 컨트롤 자원을 의미하는 경우 예외적으로 동사를 사용한다.

❌ http://cocoon1787.tistory.com/duplicating

⭕ http://cocoon1787.tistory.com/duplicate

URL은 자원을 표현하는데 중점을 두기 때문에 동사, 형용사보다는 명사를 사용하여야 합니다.

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

REST 리소스 간에는 연관 관계가 있을 수 있고, 이런 경우 다음과 같은 표현방법으로 사용합니다.

    /리소스명/리소스 ID/관계가 있는 다른 리소스명

    ex)    GET : /users/{userid}/devices (일반적으로 소유 ‘has’의 관계를 표현할 때)

만약에 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현하는 방법이 있습니다. 예를 들어 사용자가 ‘좋아하는’ 디바이스 목록을 표현해야 할 경우 다음과 같은 형태로 사용될 수 있습니다.

    GET : /users/{userid}/likes/devices (관계명이 애매하거나 구체적 표현이 필요할 때)

자원을 표현하는 Colllection과 Document

Collection과 Document에 대해 알면 URI 설계가 한 층 더 쉬워집니다. DOCUMENT는 단순히 문서로 이해해도 되고, 한 객체라고 이해하셔도 될 것 같습니다. 컬렉션은 문서들의 집합, 객체들의 집합이라고 생각하시면 이해하시는데 좀더 편하실 것 같습니다. 컬렉션과 도큐먼트는 모두 리소스라고 표현할 수 있으며 URI에 표현됩니다. 예를 살펴보도록 하겠습니다.

http://restapi.example.com/sports/soccer

위 URI를 보시면 sports라는 컬렉션과 soccer라는 도큐먼트로 표현되고 있다고 생각하면 됩니다. 좀 더 예를 들어보자면

http://restapi.example.com/sports/soccer/players/13

sports, players 컬렉션과 soccer, 13(13번인 선수)를 의미하는 도큐먼트로 URI가 이루어지게 됩니다. 여기서 중요한 점은 컬렉션은 복수로 사용하고 있다는 점입니다. 좀 더 직관적인 REST API를 위해서는 컬렉션과 도큐먼트를 사용할 때 단수 복수도 지켜준다면 좀 더 이해하기 쉬운 URI를 설계할 수 있습니다.

HTTP 응답 상태 코드

상태코드

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

400	클라이언트의 요청이 부적절 할 경우 사용하는 응답 코드
401	클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 때 사용하는 응답 코드 (로그인 하지 않은 유저가 로그인 했을 때, 요청 가능한 리소스를 요청했을 때)
403	유저 인증상태와 관계 없이 응답하고 싶지 않은 리소스를 클라이언트가 요청했을 때 사용하는 응답 코드 (403 보다는 400이나 404를 사용할 것을 권고. 403 자체가 리소스가 존재한다는 뜻이기 때문에)
405	클라이언트가 요청한 리소스에서는 사용 불가능한 Method를 이용했을 경우 사용하는 응답 코드

301	클라이언트가 요청한 리소스에 대한 URI가 변경 되었을 때 사용하는 응답 코드 (응답 시 Location header에 변경된 URI를 적어 줘야 합니다.)
500	서버에 문제가 있을 경우 사용하는 응답 코드

잘 설계된 REST API는 URI만 잘 설계된 것이 아닌 그 리소스에 대한 응답을 잘 내어주는 것까지 포함되어야 합니다.
정확한 응답의 상태코드만으로도 많은 정보를 전달할 수가 있기 때문에 응답의 상태코드 값을 명확히 돌려주는 것도 중요한 일입니다.

참고

서버 API 통신과 REST API: https://velog.io/@blackb0x/%EC%84%9C%EB%B2%84-API-%ED%86%B5%EC%8B%A0%EA%B3%BC-REST-API
[Network] REST란? REST API란? RESTful이란?: https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html
API, HTTP API, REST API 차이: https://bentist.tistory.com/37
REST API 제대로 알고 사용하기: https://meetup.toast.com/posts/92

저작자표시 비영리 변경금지