RESTful API란

API의 개념

API(Application Programming Interface)는

응용 프로그램에서 사용할 수 있도록 운영체제나 프로그래밍 언어가 제공하는 기능을 제어하기 위한 인터페이스입니다.

인터페이스가 무엇인지 알면 API를 쉽게 이해할 수 있습니다. 인터페이스는 'inter(~사이의)'와 'face(면)'가 합쳐진 말로 여러 장치나 프로그램 사이에서 통신이 가능하도록 도와주는 매개체를 가리킵니다. 

ex) 키보드는 사용자의 컴퓨터가 상호작용할 수 있도록 명령어를 입력하는 사용자 인터페이스. 사용자는 키보드를 통해 손쉽게 명령을 내릴 수 있음

 

키보드가 사용자와 컴퓨터 사이의 통신을 가능하게 한다면, API는 응용 프로그램과 응용 프로그램 사이의 통신을 가능하게 합니다.
예를 들어 네이버에 접속하는 경우를 생각해 봅시다. 사용자가 웹 브라우저에 'https://ww.naver.com'을 입력하면 네이버가 뜹니다. 이는 데이터를 조회하는 (GET) API가 호출된 것으로,  '네이버 사이트를 보여달라'는 요청에 서버가 응답한 결과입니다.
API 요청은 이처럼 주소창에 도메인을 직접 입력하는 것뿐만 아니라 웹사이트의 메뉴, 이미지, 아이콘을 클릭하는 동작으로 호출할 수 있습니다.

 

클라이언트와 서버는 API를 호출해 요청과 응답을 주고 받습니다. 클라이언트가 API를 호출해 필요한 데이터를 서버에 요청하면, 서버는 데이터베이스에 데이터를 처리한 후 그 결과를 클라이언트에 응답합니다. 

API 개발 순서

엔드포인트 설계 > HTTP 메소드 지정 > 데이터 포맷 및 프로토콜 선택 > 엔드포인트 구현 > 인증 및 보안 > 오류 및 예외 처리 > 테스트와 디버깅 > API 문서화

 

엔드포인트 설계

요청을 보낼 서버의 주소를 설정하고(예 : https://www.naver.com), 해당 경로에 대해 어떤 API를 요청할지 최종 엔드포인트(/search, /user)를 를 정의합니다. 다음과 같이 하나의 경로에 여러 엔드포인트를 지정할 수 있습니다.

- https://www.naver.com/search 

- https://www.naver.com/user

 

HTTP 메소드 지정

각 엔드포인트에 요청할 HTTP 메소드를 지정합니다.
HTTP 메소드는 클라이언트가 서버로 보내는 요청의 종류로,
POST(데이터 생성), GET(데이터 조회), PUT 또는 PATCH(데이터 수정), DELETE(데이터 삭제)가 있습니다.

 

데이터 포맷 및 프로토콜 선택

API에서 사용할 데이터 포맷, 즉 주고 받을 데이터의 형태와 통신에 사용할 프로토콜을 선택합니다.
일발적으로 데이터 포맷은 JSON, 프로토콜은 RESTful을 많이 사용합니다. 

 

엔드포인트 구현

각 엔드포인트로 접수된 클라이언트의 요청을 처리하는 서버 측 로직을 구현합니다. 클라이언트의 요청을 받으면 데이터베이스에 접근해 데이터를 가져와 가공하고, 이를 클라이언트에 반환하는 프로그램 로직을 만듭니다.

 

인증 및 보안

API를 보호하기 위해 인증 및 보안 매커니즘을 구현합니다. 사용자 인증, 액세스 토큰 기반의 권한 부여, 암호화 등의 보안 기능이 포함됩니다.

 

오류 및 예외처리

잘못된 요청이나 예외 상황에 대해 적절한 오류 응답을 할 수 있도록 프로그램 로직을 보강합니다. 이를 통해 클라이언트가 오류를 인식하고 적절히 처리할 수 있습니다.

 

테스트와 디버깅

API 개발 작업은 테스트와 디버깅 단계를 거쳐야 합니다. 그림으로써 API의 정확성과 안정성을 확인하고, 문제를 해결하며, 성능을 최적화 할 수 있습니다.

 

API 문서화

API를 사용하는 다른 개발자가 쉽게 이해하고 사용할 수 있도록 문서화하는 단계입니다. API의 엔드포인트, 매개변수, 응답 형식, 오류 코드 등에 대한 명세를 문서로 작성함으로써 개발자가 API를 좀 더 효과적으로 활용할 수 있습니다. 

 

---

REST API

API의 형식이 너무 자유로우면 개발자끼리 API를 이해하고 사용하는데 오랜 시간이 걸립니다.
따라서 이를 해결하기 위해 API 작성 규칙을 표준화한 REST API(REpresentational StateTreansfer API) 가 개발 되었습니다. 

 

쉽게 말해 REST API는 REST를 적용한 API입니다.
REST는 웹의 장점을 활용해 만든 API 설계 스타일로, 미국의 컴퓨터 과학자인 로이 필딩(Roy Fielding)이 2000년 박사 학위 논문에서 처음 소개했습니다.그는 당시 누가 개발했는지에 따라 웹 사이트 별로 URL이 천차만별이고, 심지어 URL에 파일명까지 노출되는 것을 보고 REST를 개발 했습니다.

 

REST API의 요소

REST API는 크게 자원(resource), 행위(verb), 표현(representation of resource)으로 구성됩니다.

 

자원

REST API는 클라이언트와 서버가 주고 받는 자원(테스트, 이미지, 음악, 영상 등)을 URI로 명시합니다. URI는 URL보다 상위 개념으로, 특정 자원 자체를 의미합니다. 한편 URL은 웹상에서 자원이 있는 곳의 위치를 뜻합니다. 예를 들어 네이버 사이트의 사용자 페이지 URL이 https://www.naver.com/users라면 면 100버째 사용자를 가리키는 URI는 https://www.gilbut.co.kr/users/100이 될 수 있습니다

 

URI의 구조는 다음과 같습니다.

scheme : [//[user[:password]@]host[:port][/path][?query][#fragment]

• scheme : 사용자 프로토콜의 종류(http, https 등)를 나타냅니다.
• user와 password : 서버에 저장된 데이터 접근하는데 필요한 사용자의 이름과 비밀번호로, 없는 경우 생략할 수 있습니다. 
• host와 port : 접근할 서버의 호스트명(도메인, IP주소 등)과 같은 포트 번호입니다.
• path : 접근할 서버의 경로에 대한 상세 정보입니다.
• query : 접근할 대상에 전달하는 추가 정보입니다.
• fragment : 메인 자원 내에 있는 서브 자원에 접근할 때 이를 식별하기 위한 정보입니다.

 

행위

행위란 HTTP 메소드를 통해 해당 자원에 CRUD 연산을 적용하는 것을 의미합니다.
각 연산에 사용하는 HTTP 메소드는 다음과 같습니다.

• Create(데이터 생성) : POST
• Read(데이터 조회) : GET
• Update(데이터 수정) : PUT 또는 PATCH
• Delete(데이터 삭제) : DELETE

 

표현

클라이언트가 서버에 자원을 요청하면 서버는 요청받은 시점의 자원 상태를 반환합니다. 자원 상태는 CRUD 연산에 의해 매번 바뀝니다. 예를 들어 사용자 정보는 회원 가입, 탈퇴, 정보 수정 등으로 인해 실시간으로 바뀝니다. REST API는 이렇게 변하는 자원 상태를 반영해 요청받은 시점의 자원 상태를 반환합니다. 이때 주고 받은 자원, 즉 데이터의 형식은 JSON 또는 XML입니다.

 

정리하자면 REST API는 네트워크 상에서 클라이언트와 서버가 주고 받는 자원에 이름을 붙여, HTTP 메소드로 특정 자원에 대한 CRUD 연산을 요청하고, 그에 대한 응답으로 JSON 또는 XML 데이터를 응답하는 방식으로 동작합니다.

REST API의 동작

 

 

REST API의 특징

REST API의 가장 큰 특징은 HTTP 요청 메시지만 보고도 어떤 동작이나 정보를 요청하는지 쉽게 이해할 수 있다는 것인데요.
한 예로 다음 HTTP 요청 메시지를 살펴보도록 하겠습니다.

POST /users HTTP/1.1 -- 시작행
		  	-- 헤더
                     -- 빈행
                     
{
	"name" : "Bamsae"
 }

 

메시지의 시작행에 있는 POST는 데이터를 생성하라는 HTTP 메서드입니다. 그리고 /users는 데이터 생성 요청을 보내는 URI입니다. 본문에서는 "name"속성 값으로 "bamsae"를 보냅니다. 개발자는 이를 통해 Bamsae라는 이름을 가진 사용자를 생성하라는 요청을 보냈다는 것을 추론 할 수 있습니다. 이렇게 REST의 원칙과 제약을 준수해 설계한 API를 'RESTful한 API'라고 합니다. 

 

반면에 다음 코드에서는 1번 사용자를 생성하라는 요청인지, 삭제하라는 요청인지 판단하기 어렵습니다. 아래에 본문이 있는 것으로 봐서는 생성요청이 맞는 것 같지만 RESTful 하지 않은 API입니다.

POST /delete/user HTTP/1.1 -- 시작행
		  	-- 헤더
                     -- 빈행
                     
{
	"name" : "Bamsae"
 }

 

 

REST API 설계 규칙

그렇다면 RESTful한 API는 어떻게 구현할까요? REST API를 설계 할때의 핵심은 세가지 구성요소, 즉 자원 , 행위, 표현을 역할에 맞게 잘 활용하는 것입니다. URI로 자원을 표현하고 자원에 대한 행위는 HTTP 메서드로 표현한다는 사실을 염두에 두고 REST API 설계 규칙을 살펴봅시다.

1. URI에 명사를 사용합니다.
   • 예시
     • /getUsers (잘못된 예시)
     • /users (올바른 예시)
   • URI는 자원을 식별하기 위한 것이므로 동사보다는 명사를 사용해야 합니다. /getUsers와 같은 URI는 동사를 사용하여 자원을 얻는 것이 아니라, /users와 같이 명사를 사용하여 자원을 표현해야 합니다.
2. 자원의 계층관계를 '/'로 나타냅니다.
   • 예시
     • /users123/orders (잘못된 예시)
     • /users/123/orders (올바른 예시)
   • URI의 각 세그먼트는 자원의 경로를 나타내며, /users123/orders와 같이 계층적인 관계를 나타내는 구조가 아니라면 올바르지 않습니다. /users/123/orders와 같이 계층 구조를 명확히 표현해야 합니다.
3. 마지막에 /를 넣지 않습니다.
   • 예시
     • /users/ (잘못된 예시)
     • /users (올바른 예시)
   • URI의 끝에 슬래시(/)를 포함할 경우, 동일한 자원을 가리키는 URI가 중복되는 문제가 발생할 수 있습니다. 또한, 슬래시를 사용하는 것과 사용하지 않는 것 사이의 일관성이 없어지므로, 마지막에 슬래시를 넣지 않는 것이 좋습니다.
4. 명사와 명사를 구분할 때 '-'를 사용합니다.
   • 예시
     • /userDetails (잘못된 예시)
     • /user-details (올바른 예시)
   • URI의 각 단어를 구분하는 데에는 하이픈(-)을 사용하는 것이 가독성이 높고 일관성 있는 URI를 유지하는 데 도움이 됩니다.
5. _이 아닌 -을 사용합니다.
   • 예시
     • /user_details (잘못된 예시)
     • /user-details (올바른 예시)
   • URI에 사용되는 문자로는 언더스코어(_)보다 하이픈(-)을 사용하는 것이 보다 일반적이고 권장되는 방식입니다.
6. 소문자만 사용합니다.
   • 예시
     • /Users (잘못된 예시)
     • /users (올바른 예시)
   • URI는 대소문자를 구분하므로, 일관성을 유지하기 위해 소문자만을 사용하는 것이 좋습니다.
7. 파일 확장자를 포함하지 않습니다.
   • 예시
     • /users.json (잘못된 예시)
     • /users (올바른 예시)
   • REST API는 보통 JSON 또는 XML과 같은 형식의 데이터를 반환하므로, URI에 파일 확장자를 포함할 필요가 없습니다. URI는 단순히 자원을 식별하는 용도로만 사용되어야 합니다.
8. 적절한 HTTP 상태 코드를 응답합니다.
   • 예시
     • 200 OK (올바른 예시)
     • 500 Internal Server Error (올바른 예시)
   • HTTP 상태 코드는 클라이언트에게 요청의 성공 또는 실패를 알려주는 중요한 역할을 합니다. 따라서 적절한 상태 코드를 반환하여 클라이언트에게 응답 상태를 명확히 전달해야 합니다.

 

 

참고자료

https://brunch.co.kr/@rlatjrwn9086/62

데이터로 하는 대화의 규칙

https://velog.io/@somday/RESTful-API-%EC%9D%B4%EB%9E%80

RESTful API 이란

https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Fielding Dissertation: CHAPTER 5: Representational State Transfer (REST)

https://restfulapi.net/

What is REST?: REST API Tutorial