다시 정리해보는 REST API

매년 경력이 쌓이면서 경력 값 하는 개발자가 되어야겠다고 다짐했다.

처음 개발을 배울 때는 자바와 JSP, HTML, Javascript만 있는 줄 알았지만, 일을 하고 배워가면서 정말 많은 종류가 있다는 것을 알았을 때에는 조금 혼란스러웠다. 무엇을 배워야 도움이 될지 선택하기가 어려웠다.

 

하지만 요즘은 프론트엔드 / 백엔드 개발자가 되기 위한 로드맵이 잘 갖추어져 있다. 로드맵을 따라 하나씩 배우다 보면 어느샌가 자신이 목표로 하는 분야에 조금씩 가까워질 거라고 생각한다.

 

로드맵은 https://roadmap.sh/backend 여기에서 참고했다. 백엔드 말고도 여러 분야의 로드맵이 있다.

Developer Roadmaps

위의 로드맵을 보면서 나는 어떤 기술 스택을 가지고 있고, 다룰 수 있는지 정리해보면 좋겠다는 생각이 들었다.

API (Application Programming Interface)란?

API는 Application Programming Interface의 줄임말로, 애플리케이션(소프트웨어) 간에 통신 방법을 정의하는 것을 뜻한다.

주로 요청(Request)과 응답(Response)으로 이루어져 있으며 클라이언트와 서버의 관계에서, 웹 API 또는 REST API로 많이 사용된다.

하나의 웹 프로젝트 안에서 작업할 때는 크게 신경 쓰지 않았다. JSP나 타임리프 등의 템플릿 언어로 구성한 화면에서 어느 정도 사용하기 편하게 변수명을 짓고 해당 화면으로 보내면 되었기 때문이다.

 

그러나 요즘은 프런트엔드와 백엔드 프로젝트를 분리하여 작업하는 방식이 많아졌다. 프런트에서 백으로 데이터를 요청하고 백에서는 요청받은 데이터를 가공하여 프런트로 다시 응답해주어야 한다. 이때 서로 간의 규칙이 정해져 있지 않으면 데이터를 전달하기가 매우 어렵다.

 

그래서 이러한 문제점을 해결하기 위해 여러 방식들이 사용된다.

- 요청과 응답 방식 정의 REST (Representational state transfer)

- 데이터 전달을 위한 JSON (Javascript Object Notation)

- 로그인을 위한 토큰 인증 JWT (JSON Web Token)

등이 있다. 위 목록에 나열한 기술들은 이후 포스팅을 통해 자세히 정리할 예정이다.

웹 API 흐름과 동기 / 비동기

웹 API의 기본적인 흐름도는 아래와 같다.

1. 화면(프런트엔드)에서 서버(백엔드)로 데이터를 요청한다.
2. 서버는 요청에 대한 작업을 수행한다.
3. 서버는 필요할 경우 데이터 저장소(DB)와 통신하여 데이터를 가져온 후 가공한다.
4. 화면의 요청에 대한 응답에 데이터를 포함하여 보낸다.

 

API는 요청과 응답이 한 쌍이다. 서버가 요청을 받았다면 반드시 응답해야 한다.

또한 화면에서 요청했다면 응답을 기다려야 한다. 기다리는 동안 다른 작업은 할 수 없다.

이런 방식을 동기(Synchronous)식이라고 한다.

 

이에 반대되는 방식은 비동기(Asynchronous)식이다. 주로 Ajax를 통해 작업한다.

동기식은 요청 후 응답을 받을 때까지 대기 상태가 되므로 다른 작업을 할 수 없다.

그러나 비동기식은 중간자의 개념이 추가된다. 중간자를 통해 요청하고 응답을 대기한다. 응답을 받았다면 화면에 전달해준다.

이로 인해 화면이 멈추지 않고도 데이터를 주고받을 수 있게 된다.

REST API란?

Representational State Transfer라는 용어의 약자로, 웹의 장점을 최대한 활용할 수 있는 아키텍처이다.
RESTful API라는 용어는 일반적으로 RESTful 웹 API를 나타낸다.

REST API 요청에 포함된 요소는 어떤것이 있을까?

고유 리소스 식별자

서버는 고유한 리소스 식별자로 각 리소스를 식별한다. 일반적으로 URL(Uniform Resource Locator)를 사용하여 리소스 식별을 수행한다.
요청 엔드포인트라고도 하며 클라이언트가 요구하는 사항을 서버에 명확하게 지정한다.

메서드

• GET
  특정 데이터를 조회할 때 주로 사용한다. GET 요청에 데이터를 포함하여 보낼 수 있다. 민감하거나 중요한 정보는 포함하지 않도록 한다.
• POST
  데이터를 생성할 때 사용한다. GET 요청과 마찬가지로 데이터를 포함하여 보낼 수 있다. 동일한 POST 요청을 여러번 전송하면 동일한 데이터를 여러번 생성하는 부작용이 있다.
• PUT
  기존의 데이터를 수정할 때 사용한다. POST와는 달리 여러번 요청해도 결과는 동일하다. 수정 요청시 모든 필드를 필요로 한다.
• PATCH
  역시 데이터를 수정할 때 사용하나 PUT과는 다르게 수정할 일부 필드만 필요로 한다.
• DELETE
  데이터를 삭제할 때 사용한다.

HTTP 헤더

요청 헤더는 클라이언트와 서버 간에 교환되는 메타데이터이다.

• 데이터
  POST, PUT 및 기타 HTTP 메서드가 성공적으로 작동하기 위한 데이터가 포함될 수 있다.
• 파라미터 수행해야 할 작업에 대한 자세한 정보를 서버에 제공하는 파라미터가 포함될 수 있다.
  • URL 세부정보를 지정하는 경로 파라미터
  • 리소스에 대한 추가 정보를 요청하는 쿼리 파라미터
  • 클라이언트를 빠르게 인증하는 쿠키 파라미터

REST API 응답에 포함된 요소는 어떤것이 있을까?

상태 표시줄

상태 표시줄에는 요청 성공 또는 실패를 알리는 3자리 상태 코드가 있다.
일반적인 상태 코드로는

• 200 OK: 일반 성공 응답
• 201 Created: POST 메서드 성공 응답
• 400 Bad Request: 서버가 처리할 수 없는 잘못된 요청
• 404 Not Found: 리소스를 찾을 수 없음
• 500 Internal Server Error: 서버에 문제가 있음
• 503 Service Unavailable: 서버가 요청을 처리할 준비가 되어있지 않음

더 자세하고 다양한 상태 코드는 HTTP 상태 코드 정리 참고

메시지 본문

요청 헤더에 포함된 내용을 기반으로 적정한 표현 형식을 선택하여 리소스를 표현한다.
주로 JSON 형식의 리소스를 반환한다. ex) {"name":"John", "age":30}

헤더

응답에 대한 헤더 또는 메타데이터를 포함한다. 서버, 인코딩, 날짜및 콘텐츠 유형과 같은 정보를 포함한다.

REST API 인증 방법이란 무엇인가?

RESTful 웹 서비스는 응답을 보내기 전에 먼저 요청을 인증해야 한다. 클라이언트는 서버와의 신뢰를 구축하기 위해 서버에 자신의 신원을 증명해야 한다.

주로 4가지의 일반적인 인증 방법이 있다.

HTTP 인증

• 기본 인증
  클라이언트는 요청 헤더에 사용자 이름과 암호를 넣어 전송한다. 보안을 위해 인코딩하여 보내야 한다.
• 전달자(Bearer) 인증
  토큰 전달자에 대한 엑세스 제어를 제공하는 프로세스이다. 일반적으로 전달자 토큰은 서버가 로그인 요청에 대한 응답으로 생성하는 암호화된 문자열로 주로 JWT(Json Web Token)을 사용하여 구현한다.
  클라이언트는 해당 토큰을 요청 헤더에 넣어 전송한다.

API 키

API 키는 REST API 인증을 위한 또 다른 옵션으로 이 접근 방식에서 서버는 고유하게 생성된 값을 최초 클라이언트에 할당한다. 클라이언트는 리소스에 액세스하려고 할 때마다 고유한 API 키를 사용하여 본인을 검증한다. API 키의 경우 클라이언트가 이 키를 전송해야 해서 네트워크 도난에 취약하기 때문에 덜 안전하다.

OAuth

OAuth는 모든 시스템에 대해 매우 안전한 로그인 액세스를 보장하기 위해 암호와 토큰을 결합한다. 서버는 먼저 암호를 요청한 다음 권한 부여 프로세스를 완료하기 위해 추가 토큰을 요청한다. 특정 범위와 수명으로 언제든지 토큰을 확인할 수 있다.

REST API 설계 가이드

1. URI는 정보의 자원을 표현해야한다. 동사보다는 명사를 사용한다.
2. 행위는 HTTP 메서드를 사용해야 한다. 행위를 URI에 표현하지 않도록 한다.

GET /users/1        //서버의 users 리소스 중 1번 데이터를 조회
POST /users         //서버에 새로운 users 리소스를 생성 
PUT /users/1        //users 리소스의 1번의 데이터를 수정 
DELETE /users/1     //users 리소스의 1번 데이터를 삭제

3. 슬래시(/)는 계층 관계를 나타내기 위해 사용한다. 뒤에 붙는 슬래시는 URI에 포함하지 않도록 한다.

/users/frontend/vue 
/users/backend/java

4. URI의 가독성을 향상시키기 위해 영어 소문자와 하이픈(-)을 사용한다. 언더바(_) 또는 스네이크케이스, 카멜케이스, 파스칼케이스 등은 사용하지 않도록 한다.

/app-dev/android  (O) 
/appDev/android   (X)  카멜케이스 
/AppDev/Android   (X)  파스칼케이스 
/app_dev/android  (X)  폰트 또는 태그에 따라 언더바가 제대로 표현되지 않을 수 있음 
/APP-DEV/ANDROID  (X)  처음것과 같은것으로 간주

5. URI에 파일 확장자를 포함하면 안된다. 요청 헤더의 Media Type에 포함하여 요청해야 한다.

참고 사이트

• RESTful API란 무엇인가 ?
• REST API와 설계원칙(2)