[REST API] REST API 란 무엇이고 어떻게 잘 사용해야 하는 것인가.

gogori6565·2024년 7월 21일
0

스프링 부트 공부

목록 보기
16/20

API 란?

우선, API란 무엇인지 간략하게 정리해보자.

API (Application Programming Interface)
: 두 어플리케이션이 서로 상호작용(통신)하는 것을 도와주는 매개체의 역할을 하는 것으로,
응용 프로그램에서 사용할 수 있도록 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스이다.

API를 쉽게 이해하기 위해, 레스토랑의 운영 방식에 빗대어 표현하면,
API는 레스토랑에서 손님으로부터 주문을 받은 음식을 요리사에게 요청하고, 완성된 요리를 다시 손님에게 가져다 주는 점원과 같은 역할을 한다.
손님(요청하는 프로그램)이 주문할 수 있게 메뉴(명령 목록)를 정리하고, 주문(명령)을 받아 요리사(요청 받은 응용프로그램)와 상호 작용해 요청된 메뉴(명령에 대한 값)를 다시 전달한다.

  • 라이브러리/프레임워크 에서 우리가 이용할 수 있는 class 나 함수를 API라고 한다
  • 외부 뿐만 아니라 프로젝트 내부에서 쓰여지고 있는 class나 모듈이 있다면 그것 역시도 API !!
  • 내부 구현사항을 잘 숨겨두고 외부에서 사용할 사람이 필요한 것만 노출해두는 것을 인터페이스, 즉 API라고 부른다.

추가로, OpenAPI는 회사 내부에서 사용하는 WebAPI를 외부의 다른 개발자가 이용할 수 있도록 공개적으로 오픈하는 것을 말한다.

➕ URL vs URI
URL : 자원이 실제 존재하는 '위치'
URI : 자원에 대한 '고유 식별자'

https://www.gogori6565.co.kr => URL
gogori6565.co.kr => URI

REST API 란?

자 그럼 본래의 목적으로 돌아와서, REST API가 무엇인지 살펴보자.

REST

REST(Representational State Transfer)
: 자원을 이름으로 구분해서 해당 자원의 상태를 주고받는 모든 것을 의미

즉, REST 란

  1. HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고,
  2. HTTP Method(POST, GET, PUT, PATCH, DELETE 등)를 통해
  3. 해당 자원(URI)에 대한 CRUD Operation을 적용하는 것을 의미한다.

< REST 구성 >

  1. 자원 (Resource) : URI
  2. 행위 (Verb) : HTTP 메서드
  3. 표현 (Representations)

REST API

REST API(Representational State Transfer API)
: REST의 원리를 따르는 API.

REST API를 구현하기 위해서는 몇 가지 설계 원칙을 따라야 한다.

📌 REST API 설계 규칙

1. URI는 동사(Verb)보다는 명사(Noun)를 사용하자.

http://gogori6565.com/read-articles (X)
http://gogori6565.com/articles 		(O)

2. URI는 대문자보다는 소문자를 사용하자.

http://gogori6565.com/Articles 		(X)
http://gogori6565.com/articles 		(O)

3. 슬래시 / 구분자를 통해 자원 간의 계층 관계를 나타내자. (단, 마지막에 슬래시 / 를 넣지 않는다.)

http://gogori6565.com/articles/1/ 	(X)
http://gogori6565.com/articles/1 	(O)

4. 언더바 _ 대신 하이픈 - 을 사용하자.

http://gogori6565.com/h2_console 	(X)
http://gogori6565.com/h2-console 	(O)

5. 파일확장자는 URI에 포함하지 않는다.

http://gogori6565.com/photo.jpg		(X)
http://gogori6565.com/photo			(O)

📌 REST API 설계 원칙

1. Uniform Interface(일관된 인터페이스)
데이터를 식별 가능하게 해야한다는 원칙으로, 사실상 개발자들이 집중해야 하는 원칙이다.
구체적으로는 간결, 일관적이어야 하며 URL만 보고도 어느 데이터를 어떤 상태로 전송해야 하는지 구별할 수 있어야 한다.
이를 지키기 위한 REST API 설계 규칙이 바로 위에 작성한 규칙들이다.

2. Client Server
클라이언트와 서버는 반드시 분리되어야 하고, 클라이언트는 데이터를 서버에 요청하고, 서버는 클라이언트의 요청에 따른 데이터를 응답해야 한다.

3. Stateless (무상태성)
클라이언트의 요청에는 해당 요청을 이해할 수 있는 모든 정보가 포함되어야 한다.
그리고 서버는 그러한 클라이언트의 상태정보를 저장하지 않는다. 컨텍스트를 유지해야하는 세션, 인증과 인가에 대한 정보 또는 클라이언트에만 보관되며, 각 요처 시 해당 정보를 모두 포함해 서버에 요청한다.

4. Cacheable
요청을 통해 보내는 자료들은 저장되어야 한다. 이를 통해 저장된 자료들을 또 주고 받을 때 속도를 향상시킬 수 있다.

5. Layered System(다중 계층)
요청된 정보를 검색하는데 계층 구조로 분리되어 있어야 한다. 예를 들어 API 서버와 DB 서버 그리고 인증 서버를 둬서 서버 확장성을 보장한다.

6. Code on Demand
서버가 클라이언트에서 실행시킬 수 있는 로직을 전송해 클라이언트의 기능을 확장시킬 수 있다.
이를 통해 클라이언트가 사전에 구현해야 하는 기능의 수를 줄여 간소화시킬 수 있다.

👉 1번 원칙을 제외하고 나머지 원칙들은 인터넷을 사용함으로써 자연스럽게 지켜지기에, API를 설계하는 개발자들은 1번 원칙을 지키기 위해 노력해야 한다.

Restful 이란?

: Rest 원칙을 따르는 시스템

즉, 설계규칙을 올바르게 지키지 못했거나 모든 CRUD를 POST로 처리했다면 이는 RestAPI를 사용했지만 Restful 하지는 못한 시스템이라고 말한다.

Path Parameter vs Query String

REST API는 상황에 따라서 path parameter와 query string을 통해 통신할 수 있다. 이 두가지의 차이점은?!

Path Parameter

API URI로 통신을 하는 것을 Path Parameter를 사용하여 통신한다고 한다.
REST API를 떠올렸을 때 가장 기본으로 떠오르는 아래와 같은 코드들을 사용하는 것이 바로 Path Parameter 이다.

GET http://localhost:8080/articles			#게시글 전체 가져오기
POST http://localhost:8080/articles			#게시글 등록하기 (POST의 경우, request body에 등록할 정보를 실어 보냄)
PATCH http://localhost:8080/articles/1		#1번 게시글 수정하기
DELETE http://localhost:8080/articles/1		#1번 게시글 삭제하기

request body 는 client 입장에서 API 명세서에 맞게보낸 요청 데이터들이고,
reponse body는 client가 요청 후 받는 데이터들을 이야기한다.

POST로 예를 들면,

{
	"name":"홍길동",
    "age" :18
}

이라는 request body 를 보내면,
서버에서 DB에 해당 정보를 등록하면서 자동으로 id값을 생성하고 아래와 같은 response body를 돌려주는 것이다.

{
	"id"  :3,
	"name":"홍길동",
    "age" :18
}

Query String

query parameters(물음표 뒤에 = 로 연결된 key value pair 부분)을 URI 뒤에 덧붙여 추가적인 정보를 서버 측에 전달하는 것이다.

GET http://library.com/books?status=available

이 코드의 경우, status=available 로 빌릴 수 있는 책을 가져오라는 조건을 걸어준 것이다.

GET http://library.com/books?page=1&size=10

그리고 이것은 페이징 처리라고 하여, 1페이지에 10권씩 가져오라는 의미이다.
(필터링 정보 없이 books 만 입력해 모든 데이터를 가져올 수 있지만 그렇게하면 부하가 걸리니까 이렇게 페이징 처리를 해주는 게 좋다)

<Query String 형식>

  • 정해진 엔드포인트 주소 이후에 ?를 써서 query string의 시작을 알린다
  • parameter=value 로 필요한 파라미터의 값을 적는다
  • 파라미터가 여러 개일 경우 & 를 사용한다
  • = 로 key와 value가 구분된다

Path Parameter vs Query String 어떤 걸 사용할까?

  • Path Parameter 는 '원하는 조건의 데이터'들 혹은 '하나의 데이터''에 대한 정보를 받아올 때 적절하고,
  • Query String 은 filtering, sorting, serching 에 적절하다.

참고 사이트
https://www.youtube.com/watch?v=fB3MB8TXNXM - REST API 란 (영상)
https://khj93.tistory.com/entry/%EB%84%A4%ED%8A%B8%EC%9B%8C%ED%81%AC-REST-API%EB%9E%80-REST-RESTful%EC%9D%B4%EB%9E%80 - REST API 란
https://ziszini.tistory.com/91 - REST API 설계 원칙
https://velog.io/@haileeyu21/Session-RESTful-API-%EB%9E%80-Path-parameters-Query-string - Path Parameter vs Query String

profile
gogori6565
p(´∇｀)q
이전 포스트

[Spring Boot] #18. RestAPI와 JSON

다음 포스트

[Spring Boot] #19. HTTP와 RestController

0개의 댓글