REST APIs Explained - 4 Components

REST APIs Explained - 4 Components

 

기본 개념

 

REST API는 웹에서 정보를 얻고자 하는 클라이언트(사람 또는 애플리케이션)와 그 정보를 접근할 수 있는 서버(애플리케이션 또는 데이터베이스) 간에 가장 일반적으로 사용되는 표준이다.

애플리케이션 프로그래밍 인터페이스(API)

• 두 컴퓨터가 웹을 통해 서로 통신할 수 있는 방법
• 배달 앱에서 자체적으로 위치 추적 시스템을 구축하는 대신 Google Maps API를 사용하여 위치 추적을 지원할 수 있다.

RESTful

• REST 표준을 따르는 API

---

Basic format

RESTful API의 형식에는 세 가지 주요 구성 요소가 있다: 1) URL endpoint; 2) HTTP verb; and 3) Body.

 

URL endpoint

• 액세스하고자 하는 리소스를 나타내는 URL 링크
• 리소스 : 텍스트, 이미지, 문서 또는 기타 데이터 항목
• 예를 들어 example.com/surveys는 설문조사 템플릿을 조회하거나 생성할 수 있게 하고, example.com/surveys/123/responses는 설문조사 123의 모든 응답을 조회하거나 생성할 수 있게 한다.

HTTP verb

• URL endpoint 리소스에 대해 무엇을 하고자 하는지를 서버에 알려준다.
• 예를 들어 POST 요청은 새로운 설문조사 템플릿을 생성하고자 한다는 의미이며, GET 요청은 기존의 설문조사 템플릿을 조회하고자 한다는 의미

Body message

• optional custom payload로 주어진 리소스를 생성하거나 업데이트하기 위해 사용하고자 하는 속성과 값을 포함한 메시지를 담고 있다.

 

e.g)  설문조사 123에 대한 새로운 응답을 생성하고자 한다. 이 응답에는 9점의 긍정적인 NPS 점수, 짧은 피드백 메시지, 그리고 피드백을 제공한 응답자의 고유 ID가 포함된다.

// Request:
POST example.com/surveys/123/responses

// Body payload:
{
  survey_id: 123, 
  nps_score: 9, 
  feedback: "love the service", 
  respondent_id: 42
}

 

서버는 HTTP 요청을 수신하고, HTTP 상태 코드와 일반적으로 JSON 형식의 응답을 포함한 응답을 반환한다.

 

e.g) 설문조사 123에 대한 모든 응답을 조회하기 위해 REST API 서버에 요청한 예시 요청과 응답 

Request:

GET http://example.com/surveys/123/responses

 

Response:

// HTTP status code: 200
{
  survey_id: 123,
  survey_title: "nps onboarding survey",
  responses: [
  {
    response_id: 42,
    nps_score: 9,
    feedback: "love the service",
    respondent_id: 42
  }
  ...
 ]
}

---

HTTP verb

HTTP 요청을 만들 때 사용하는 기본적인 명령어는 5가지가 있다.

• GET :  단일 리소스 또는 여러 리소스 목록을 보기 위한 읽기 전용 요청을 만든다.
• POST : 요청 본문에 제공된 payroad를 기반으로 새로운 리소스 생성
  • 멱등성을 가지지 않는다. 동일한 데이터로 여러 번 POST 요청을 보내면 각각의 요청에 따라 서버에 여러 개의 리소스가 생성될 수 있다.
• DELETE : 제공된 ID를 기반으로 주어진 리소스 삭제
• PUT : 요청 본문에 제공된 내용을 기반으로 리소스의 모든 필드를 업데이트하거나, 리소스가 존재하지 않는 경우 새로 만든다.
  • 멱등성을 가진다. 동일한 데이터로 여러 번 PUT 요청을 보내면 같은 결과가 된다.
• PATCH : 리소스가 존재하는 경우 필드만 업데이트한다.
  • 멱등성을 가지지 않는다. 동일한 데이터로 여러 번 보내도 각각의 요청에 따라 리소스의 상태가 서로 다를 수 있다.

Acronym	HTTP verb
Create	POST
Read	GET
Update	PUT & PATCH
Delete	DELETE

 

---

URL endpoints

RESTful API에서 URL 엔트포인트는 API가 접근할 수 있는 객체, 데이터 또는 서비스를 나타낸다.

예를 들어 example.com/surveys는 모든 설문조사 템플릿의 데이터를 나타내고, example.com/surveys/123/responses는 특정 설문조사의 모든 응답 데이터를 나타낸다.

 

• 비즈니스 데이터와 객체를 중심으로 복수형 명사로 그룹화되어야 하며, 동사가 포함되지 않아야한다.
  • example.com/surveys (o)  |   example.com/getAllSurveys(x)
• 단일 항목을 조회, 업데이트 또는 삭제할 때는 복수형 명사 뒤에 고유 식별자를 경로로 포함시켜야 한다.
  • e.g) example.com/surveys/123
• URL 컬렉션은 관계를 기반으로 논리적인 계층 구조를 구성해야 한다. 즉 서로 연결된 데이터나 리소스의 관계를 URL 경로로 명확하게 표현해야 한다.

URL endpoint resource	GET	POST	PUT	DELETE
/surveys	모든 설문조사 조회	새로운 설문조사 생성	설문조사 일괄 업데이트(권장X)	모든 설문조사 삭제(권장X)
/surveys/123	설문조사 123의 세부 정보 조회	에러	설문조사 123의 세부 정보 업데이트(존재할 경우)	설문조사 123 삭제
/surveys/123/responses	설문조사 123의 모든 응답 조회	설문조사 123에 새로운 응답 생성	설문조사 123의 응답들 일괄 업데이트(권장X)	설문조사 123의 모든 응답 삭제(권장X)
/responses/42	응답 42의 세부 정보 조회	에러	응답 42의 세부 정보 업데이트(존재할 경우)	응답 42 삭제

 

---

Status codes

기본 RESTful 형식으로 HTTP 요청을 받은 후 서버는 HTTP 상태 코드와 선택적인 JSON payroad를 함께 반환한다.

Status code	Meaning
200 OK	요청이 성공적으로 처리되었습니다.
301 Moved Permanently	SEO 목적으로 페이지가 영구적으로 이동하였으며, 모든 링크가 새 위치로 전달되어야 합니다.
401 Unauthorized	서버가 인증을 요구합니다.
403 Forbidden	클라이언트가 인증되었지만 리소스에 접근할 권한이 없습니다.
404 Not Found	페이지를 찾을 수 없습니다. 검색 결과가 없거나 재고가 없을 수 있습니다.
500 Internal Server Error	서버 측에서 오류가 발생했습니다. 일반적으로 서버 코드에서 버그나 예외가 발생했을 때 발생합니다.
503 Server Unavailable	서버가 사용할 수 없습니다. 주로 호스팅 플랫폼 문제, 과부하 또는 유지 관리 문제로 인해 발생합니다.