RESTful API란?

ReSTful API란?

ReST : Representational State Transfer

해석하면 표현 상태 이전이라는 API라는 건데 사실 정확히 어떤 의미인지는 와닿지 않는다. 그냥 간단히 이렇게 정리해보자 RESTful API는 HTTP를 더 잘 활용하기 위한 API 명세이다. 설계 방법을 조금 더 어려운 말로 명세(Specification)이라고 한다. 본격적인 설명에 앞서서 API 명세가 왜 필요한지 생각 해보자

API 명세가 필요한 이유?

API가 언제 사용되는지 생각해보자. 대표적인 예로는 웹 어플리케이션을 만들때 프론트엔드와 백엔드를 구분하고 백엔드 API를 프런트 즉 클라이언트 단에서 사용한다. 만약 API가 설계 규칙이 없이 만들어졌다면 프런트엔드에서 백엔드 API에서 원하는 응답을 반환하는 엔드포인트를 찾기위해 너무 많은 시간과 노력을 사용하게 된다.  만약 아직 프로그램 경험이 많이 없다면 와닿지 않을 것이다. 쉽게 말해서 방안에서 물건을 찾을 때 물건 물건 하나의 위치를 외워서 사용하는 것과 같은 것이다.  이러한 문제를 해결하기 위해 API를 요청하는 쪽과 구현하는 쪽에서 약속을 하고  API 구현시 이를 기준으로 하고 API에 요청을 보내는 쪽(프론트)에서도 이 약속을 바탕으로 요청하는 곳을 찾는 것이다.

HTTP Specification

위에서 RESTful API는 HTTP를 더 잘 활용하기 위한 명세라고 설명했다. 좀 더 정확히 표현해보도록 하겠다. RESTful API는 HTTP specification을 더 잘 사용하기 위한 명세이다. 엥? RESTful도 명세인데 HTTP도 명세가 있다고? 그렇다. 위에서는 명세를 설계 방법이라고 설명했지만 사실 명세는 어떤 약속에 관해 구체적으로 기술한 문서이다. HTTP 는 HyperText Transfer Protocol로 웹 문서를 전달하는 프로토콜이다. 물론 이 명세에는 굉장히 많은 사항이 있지만 우리가 봐야하는 것은 요청 메서드에 대한 부분이다. 

HTTP 요청 메서드의 종류가 많지만 메인 메서드만 설명해보자면 아래와 같다.

 

1. GET : 데이터를 갖고 올 때

2. POST : 데이터 삽입

3. PUT : 데이터 업데이트

4. DELETE : 데이터 삭제

 

프론트 단에서 서버로 요청을 보낼 때 서버가 하길 바라는 동작이 있을텐데 그 동작에 맞춰서 맞는 메서드 사용해서 요청하면 된다. 예를 들어 프런트에서 서버에 데이터를 읽어서 반환하길 바란다면 GET을 프런트에서 전송된 데이터를 데이터베이스에 삽입하길 바란다면 POST를 사용하면 된다. 흥미로운 점은 HTTP 요청 메서드가 서버의 기본 동작인 CRUD(Create, Read, Update, Delete)과 대응된다는 점인데 아래와 같이 매치된다.

 

Create ⇒ POST

Read ⇒ GET

Update ⇒ PUT

Delete ⇒ DELETE

 

 

아니 그래서 RESTful API가 뭐라고?

RESTful API는 설계 방법이라고 헀다. 그렇다면 이런생각이 들 것이다. 뭔 설계도라도 있나? 하지만 아쉽게도 그런건 아니고 몇가지 규칙을 지켜가면서 API를 설계하면된다. 그 규칙을 요약하자면 다음과 같다.

 

" 동작은 HTTP 메서드를 이용하고 갖고 와야하는 자원은 URI로 표현하자! "

이게 와닿지 않는다면 API에 들어오는 요청에 대해 생각해보자. API에 요청이 들어왔다는 뜻은 누군가 서버가 어떤 일을 하기 원한다는 것이다. 그렇다면 어떤 일을 하길 바랄까? 바로 데이터를 조작하는 것이다. 데이터를 보여주거나, 삭제하거나, 업데이트하거나, 새로 만들거나 하는 것들일 것이다. 이 때 데이터의 종류 즉 자원을 URI(ex /users, /movies, 주소뒤에 슬래쉬로 붙는 것)로 표현하고 동작을 HTTP 메서드로 표현하는 것이다. 예를 들어 user라는 데이터가 있다고 해보자 그렇다면 아래와 같이 쓸 수 있다.

 

GET /users/1 : user1 데이터를 읽어오기

POST /users/1 : user1 데이터를 만들기

PUT /users/1 : user1 데이터 업데이트

delete /users/1 : user1  데이터 제거

 

그렇다면 이렇게 사용했을 때 이점은 무엇일까? 일단 하나의 URI를 HTTP 요청 메서드 별로 다른 기능을 수행하기 때문에 전체 엔드포인트가 간단해진다.  모든 경우에 엔드포인트를 다시 써보자면 아래와 같이 적을 수 있는데 이는 가독성도 떨어지고 매번 read, create, update, delete를 모든 자원에 대해 적어줘야 프로그래밍에 피로감을 느낄 것이다.

 

/readUsers

/createUsers

/updateUsers

/deleteUsers

 

그렇다면 위에서 언급한 기본 규칙을 세부적으로 살펴보면 다음과 같다.

1. 동사를 사용하지 않는다.

URI에 동사를 사용하지 않는다. 동작은 무조건 HTTP method

2. 복수 명사를 사용할 것

자원은 복수 명사를 사용할 것, 이렇게 적는 것이 의미 파악에 더 용이하다.

3. Collections and Elements

URI의 상단에는 더 상위 범주의 자원을 쓰고 하단에 하위 범주의 자원을 적는다. 예를 들어 영화 관련되 API가 있다고 가정하면 

/movies/신세계 라고 적는 것이 RESTful한 표현

4. Relationships

URI로 이어진 자원들은 서로 상관관계가 있어야한다. 예를 들어  GET /movies/ 뒤에는 영화와 관련된 actors 같은 것이 나와야한다.

 

 

예외 사항

위에서 적은 것들 만으로는 모든 요청을 표현할 수 없다. 가령 현재 상영작이나 가장 최근에 개봉한 영화를 찾고 싶으면 어떻게 해야할까?

바로 argument를 사용하면 된다. 가령 최근 개봉한 영화를 찾고 싶다면 GET /movies?latestest=1 이런식으로 /movies 엔드포인트에서 해당 파라미터를 받아 처리하도록하면 된다.

정리

이번 포스트에서는 RESTful API에 대해 알아 보았다. Restful API는 HTTP 상세를 더 잘 사용하기 위한 API 설계 방법이고 가장 핵심 규칙은 동작은 HTTP 메서드를 이용하고 갖고 와야하는 자원은 URI로 표현하자! 이다. 다음 포스팅에서는 API 설계 방법인 GraphQL에 대해 알아보도록하겠다.