[REST API] REST API 이해하기

 

* API (Application Programming Interface)

API(Application Programming Interface, 응용 프로그램 프로그래밍 인터페이스)는 응용 프로그램에서 사용할 수 있도록, 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스를 뜻한다.

 

API가 무엇인지에 대한 위키백과의 설명이다. 얄코에서는 조금 더 쉽게 풀어서 '정보를 주고받는 데 있어서 개발자들이 사용하는 형식'이라고 설명한다.

예를 들어 기상청에서는 날씨 정보를 가지고 있다. 수많은 클라이언트들이 기상청 서버에 날씨 정보 요청을 보낸다. 이렇게 요청을 보낼 때 모두가 다른 방식으로 정보를 요청한다면 정보를 주는 입장에서도, 받는 입장에서도 엄청나게 혼란스러울 것이다. 정보를 주고받을 때 정해진 양식이 있다면 양 측 모두 편하지 않을까? 이러한 약속된 양식, 혹은 폼을 API라고 이해할 수도 있을 것이다. 

 

* REST API (Representational State Transfer API)

그렇다면 REST API란 무엇일까? 사실 순수하게 기능적인 측면만 생각해볼 때 API 양식은 개발자가 마음대로 아무렇게나 지어도 기능적으로는 돌아갈 수 있다. 예를 들어서 샌프란시스코의 날씨정보를 요청할 때 '/pier39yay' 라는 식으로 API를 정할 수도 있을 것이다. 그래도 돌아는 간다. 

하지만 기본적으로 프로그래밍은 혼자 하는 것이 아니다. '/pier39yay' 를 보고 샌프란시스코의 날씨를 요청하는 API라는 것을 알 수 있는 것은 사실상 본인밖에 없다. 협업을 전제했을 때 이런 API는 결코 바람직하지 못하다. (시간이 지나서 스스로도 알아보지 못할 가능성도 크다) 때문에 정보 요청 형식 즉, API는 내가 아닌 그 누가 보더라도 그 의도를 파악할 수 있도록 짜여져야 한다. 이렇게 짜여진 API를 REST API 혹은 RESTful API라고 한다.

 

* REST API 중심규칙

REST API를 짤 떄의 중심규칙을 크게 정리해보면 아래와 같다. 

1. URI는 정보의 자원을 포함해야 한다

- URI : 통합 자원 식별자. 자원을 구조적으로 나타내는 식별자.

// bad
GET / getweather/san-francisco

// good
GET /weather/san-francisco

동사보다는 명사를 사용한다. URI는 자원에 대한 정보를 가지고 있어야 한다. 따라서 get, post와 같이 행위에 대한 표현이 들어가면 안된다.

2. 자원에 대한 행위는 HTTP 메소드를 사용한다.

// bad
GET /weather/delete/1

// good
DELETE /weather/1

주로 5가지의 HTTP 메소드(GET, POST, PATCH, PUT, DELETE) 를 사용하여 CRUD를 구분한다. (대개 PUT은 전체를 갱신할 때, PATCH는 일부를 갱신할 때 쓰인다)

예를 들어 POST 요청을 통해서도 GET과 같이 정보를 가져오는 것이 가능하긴 하다. 하지만, REST API는 API만 보고도 이 요청이 무엇을 의미하는지를 바로 알 수 있어야 한다. POST로 GET을 요청한다면 이는 REST하다고 말하기 어려울 것이다. 따라서 가능한 한 요청에 맞는 메소드를 사용해야 한다. 

 

* URI 설계 시 유의사항

URI를 설계할 때 몇 가지 유의사항을 아래와 같이 정리해볼 수 있다. 

1. 슬래시('/')는 계층을 구분할 때 사용한다. 또한, 마지막에는 슬래시를 붙이지 않는다.

// bad
/football/baseball/

// good
/sports/football

2. URI가 길어질 경우 하이픈('-')을 사용할수 있으며, 언더바('_')는 사용하지 않는다

// bad
/football/manchester_united

// good
/football/manchester-united

3. 소문자 사용

// bad
/football/Manchester-United

// good
/football/manchester-united

 

* Reference 

- poiemaweb (https://poiemaweb.com/js-rest-api)

- toast (https://meetup.toast.com/posts/92)

- 얄팍한 코딩사전 (https://www.youtube.com/watch?v=iOueE9AXDQQ)