API는 무엇인가? REST API는 또 무엇인가? 1분 요약

들어가며

REST를 설명하기 전에 API는 무엇인지에 대해서 간략하게 짚고 넘어가보자.

API란?

API(Applictaion Programming Interface)는 프로그램 간 통신 규약으로, 서버와 클라이언트가 소통하기 위해 정해놓은 규칙이라고 할 수 있다.

# 요청 : GET        /api/movies
# 의미 : "서버야 나한테 영화목록 데이터를 좀 넘겨주련?"

API의 역할은 다음과 같이 크게 3가지로 분류할 수 있다.

• 서버와 데이터베이스의 소통창구 : 서비스를 운영할 때 고객들이 데이터베이스에 직접적으로 접근하지 못하도록 해야한다. 클라이언트가 API를 통해 서버에게 데이터를 요청하면, 서버는 데이터베이스에 접근하여 클라이언트가 요청한 데이터를 가져오고, 이를 클라이언트에게 전송해준다.
• 애플리케이션과 기기 간 원활한 통신 지원 : 웹 애플리케이션, 모바일 애플리케이션을 사용하는 기기에서 데이터를 원활하게 주고받을 수 있도록 돕는 역할을 한다.
• 모든 접속 표준화 : 기기 및 운영체제와 상관없이 누구나 동일하게 접근할 수 있다.

REST API란?

영화목록 데이터를 요청하는 API가 아래와 같이 여러개 있다고 가정해보자.

# 1) GET     /api/selectMovies
# 2) GET     /api/find_all_movies
# 3) GET     /api/getMoviesAll

# 1) POST     /api/insertMovie
# 2) POST     /api/new_movie
# 2) POST     /api/postMovie

# 1) PUT     /api/updateMovie/1
# 2) PUT     /api/edit_one_movie/1
# 2) PUT     /api/putMovie/1

# 1) DELETE  /api/removeeMovie/1
# 2) DELETE  /api/delete_one_movie/1
# 2) DELETE  /api/deleteMovie/1

기존에 API를 개발할 때에는 위와 같이 일관성이 없을 뿐더러 구조 또한 정리되어 있지 않았기 때문에 이를 활용하는데 큰 번거로움이 있었다. 이를 해결하기 위해 Roy Fielding이라는 개발자가 논문을 작성하였는데, 바로 이 논문에서 REST(Representational State Transfer) 원칙이 등장하였으며, 해당 논문이 유명해짐에 따라 현재는 REST 원칙이 API 설계 관점에서의 정론으로 받아들여지고 있다.

"REST 원칙으로 API를 개발하면 인터넷 세상이 평화로워짐"        - Roy Fielding -

REST 6 원칙

REST 원칙은 6개로 이루어져 있고, 개발자들 사이에서는 모든 원칙이 잘 지켜진 API를 보고 'RESTful 하다'라고 평가하곤 한다.

1. 유니폼 인터페이스(Uniform Interface)

• 형식을 간결하고 일관성 있게 나타낼 수 있음.
• 이를 통해 어떠한 작업이 수행되는지 예측 가능함.

2. 무상태성(Stateless)

• 작업을 위한 상태정보를 따로 저장하거나 관리하지 않음.
• 따라서, 구현이 단순해지며, 서비스의 자유도가 높아진다는 장점이 생김.

3. 캐시 가능(Cacheable)

• HTTP 기존 웹표준 그대로 사용하여 웹에서 사용하는 기존 인프라 그대로 활용 가능함.
• HTTP가 가진 캐싱 기능을 적용할 수 있음.

4. 자체 표현 구조(Self-descriptiviness)

• REST API 메시지만 보고도 이를 쉽게 이해할 수 있는 자체 표현 구조로 되어 있음.

5. Client-Server 구조

• REST 서버는 API 제공, 클라이언트 사용자 인증이나 컨텍스트(세션, 로그인 정보) 등을 직접 관리하는 구조
• 클라이언트/서버 간 개발 내용이 명확해지고 서로간 의존성이 줄어듬.

6. 계층형 구조(Layered System)

• REST 서버는 다중 계층으로 구성될 수 있음.
• 보안, 로드 밸런싱, 암호화 계층 등으로 구성하여 구조상의 유연을 확보할 수 있음.
• 프록시, 게이트웨이 등 네트워크 기반의 중간매체를 사용할 수 있음.

위의 6가지 원칙 중에서 1번 원칙을 지키는 것이 가장 중요하다. 그 이유는 API 서버 개발자는 물론, API를 활용하는 개발자들 입장에서 보았을 때에도, 해당 URL을 통해 어떠한 작업이 수행될 지 예측 가능하고, 잘 정리되어 있다면 효율적인 개발이 가능하기 때문이다(공식문서 검색 및 의도를 파악하기 위해 생각할 시간을 줄여준다)

URI 명명 요령

RESTful 한 URI을 작성하기 위해서는 몇 가지 규칙이 있다(이는 권장사항이므로 반드시 지키지는 않아도 된다).

✔ 목적에 따라 적절한 HTTP 메소드를 사용하자

• GET(조회), POST(생성), PUT(수정), DELETE(삭제)
• +) FETCH까지 사용할 경우에는 PUT(전체 수정), FETCH(일부 수정)

✔ 동사보다는 명사를 사용하자

위의 예시를 RESTful한 형태로 수정해보면 다음과 같다.

# GET     /api/movies/:id
# POST    /api/movie
# PUT     /api/movie/:id
# DELETE  /api/movie/:id

✔ 하위 경로는 /로 사용하자.

id가 2인 영화의 이미지를 요청하는 API는 다음과 같이 나타낼 수 있다.

# GET     /api/movies/2/image

마치며

위에서 언급한 명명 규칙 외에도 파일 확장자 미사용, 띄어쓰기나 _ 대신 - 사용하기 등 여러 규칙이 있으나, 위의 3가지 규칙만 잘 지켜도 RESTful한 API를 작성할 수 있다.