REST API에 대해서

의미

API(Application Programming Interface)는 서로 다른 두 프로그램이 소통할 수 있게 해준다.

웹에서는 서버와 클라이언트가 데이터를 주고 받을 때 사용된다.

 

REST API(Representational State Transfer)는 API의 한 방식으로

간단히 말하자면 URL을 통해서 데이터를 주고 받는다고 할 수 있다.

클라이언트에서 HTTP를 이용해 요청(request)을 보내면 서버에서 이에 따른 응답(response)을 보내주는 식으로 소통한다. 

 

요청

REST API로 서버에 요청을 보내기 위해서는 다음의 4가지 구성요소가 필요하다.

 

URL (endpoint)

URL은 요청할 데이터의 위치를 가리킨다.

URL은 root-endpoint와 path로 나뉘는데

root-endpoint는 서버의 기본 주소이고 path는 세부 경로다.

예를 들어 https://api.example.com/users라는 URL이 있다면 

https://api.example.com은 root-endpoint이고 /users는 path다.

 

그리하여 root-endpoint는 요청할 서버를, path는 데이터가 위치한 세부 경로를 가리킨다.

물론 특정 URL 요청이 들어왔을 때 어떤 응답을 보내줄 것인지를 서버에서 구현해 놓아야 한다.

 

때로는 옵션을 주기 위해 URL에 query parameter를 포함시키기도 한다.

하나의 query parameter는 key와 value를 쌍으로 이루고 제일 앞에 ?를 붙인다.

여러 parameter를 넣을 수 있고 각 parameter는 &로 구분한다.

https://api.example.com/users?query1=value1&query2=value2

 

Method

Method는 어떤 종류의 요청을 할 것인지를 알려준다. (CRUD)

5가지 중에 하나를 선택할 수 있다.

 

GET은 서버의 데이터를 불러올 때 사용된다. (Read)

기본값이다.

 

POST는 서버에 새로운 데이터를 추가할 때 사용된다. (Create)

 

PUT과 PATCH는 서버의 데이터를 수정할 때 사용된다. (Update)

 

DELETE는 서버의 데이터를 삭제할 때 사용된다. (Delete)

 

Header

Header는 부가적인 정보를 제공하기 위해서 사용된다.

예를 들어 클라이언트에서 서버에 보내는 데이터가 JSON 형식이라는 것을 알려준다면

"Content-Type: application/json"

서버는 데이터를 파악할 필요없이 빠르게 데이터를 읽고 처리한 다음 클라이언트에 응답할 수 있다.

 

위처럼 Header는 property와 value로 쌍을 이룬다.

(Content-Type이 property, application/json이 value)

Content-Type 이외의 property도 존재하고 사용자 인증 등 다양한 목적으로 이용된다.

developer.mozilla.org/en-US/docs/Web/HTTP/Headers

 

Body (Data)

서버에 데이터를 보낼 때 사용된다.

GET에서는 사용할 수 없다.

POST나 PUT, PATCH시 서버에 기록하거나 수정할 데이터를 여기에 담는다.

데이터는 보통 JSON 형식을 취한다.

 

응답

클라이언트가 서버에 HTTP 요청을 보내면 서버는 요청에 따른 결과가 어떻게 됐는지를 알려줘야 한다.

이를 위해 세 자리 수의 Status Code를 클라이언트에 보내준다.

 

200번대의 숫자는 요청이 잘 처리됐다는 의미다. (Success)

300번대는 다른 URL로 리다이렉트됐다는 의미다.

400번대는 클라이언트 단에서 어떤 문제가 발생했다는 의미다.

500번대는 서버 단에서 어떤 문제가 발생했다는 의미다.

 

200~

200 (OK)

요청이 성공했다.

 

201 (Created)

요청이 성공했고 하나 이상의 새로운 리소스가 생성됐다.

(POST 요청의 결과로 쓰인다.)

 

204 (No Content)

요청이 성공했고 Body로 보낼 추가적인 Content가 존재하지 않는다.

(DELETE 요청의 결과로 쓰인다.)

 

300~

301 (Moved Permanently)

요청한 리소스에 새로운 URL이 영구적으로 할당 됐고

이후에는 Response Header의 location에 포함된 URL을 이용해야 한다.

 

서버는 location Header에 URL을 포함시켜야 하고

클라이언트는 이 URL로 자동 리다이렉트 된다.

 

304

 

400~

400 (Bad Request)

syntax 에러 때문에 클라이언트의 요청을 서버가 이해할 수 없다.

 

401 (Unauthorized)

해당 리소스에 접근하려면 유효한 사용자 인증이 필요하다.

 

403 (Forbidden)

접근 권한이 없는 사용자다.

해당 접근 방식을 숨기기 위해 404를 쓰기도 한다.

 

404 (Not Found)

URL에 해당하는 리소스를 찾을 수 없다.

 

409 (Conflict)

어떤 리소스에 대한 요청을 할 때 그 리소스의 업데이트 등이 동시에 일어나 충돌해 에러가 발생했다.

 

500~

500 (Internal Server Error)

서버에 알 수 없는 에러가 발생해 요청이 실패했다.

 

참고 : 

smashingmagazine.com/2018/01/understanding-using-rest-api

httpstatuses.com