REST API와 URI 설계 규칙

 

✅ API란?

 

 - Application Programming Interface

 

 - 소프트웨어의 기능을 실행시키는 방법을 제공하는 인터페이스

    ( 예를 들면 , 우리는 API를 이용하여 휴대폰의 볼륨을 조절하는 기능, 화면을 껐다 켜는 기능을 실행할 수 있다. )

 

  - 서로 다른 소프트웨어끼리 지정된 형식으로 요청하고 응답받을 수 있게 하는 방법을 제공하는 인터페이스

  - 즉, 한 프로그램에서 다른 프로그램으로 데이터를 전달하는 방법을 명시하는 인터페이스

 

✅ REST API 필요성

 

웹서비스를 사용하는 클라이언트는 브라우저 뿐만이 아니라,

스마트폰, 태블릿, 스마트 워치, 센서, CCTV 등의 다양한 기기들이 될 수 있다.

 

웹 서버는 이처럼 다양한 종류의 모든 클라이언트들에 요청에 대해 적절히 응답해야 한다.

다시 말해, 서버는 클라이언트의 종류와 상관 없이 모든 클라이언트가 같은 응답을 받을 수 있도록 해주어야 한다.

 

이를 가능하게 해주는 개념이 바로 REST API이다.

 

 

✅ REST란?

 

 - Representational State Transfer

 

 - 웹 서비스에서 리소스를 관리하는 구조적 스타일을 의미한다.

 

 - HTTP 의 장점을 최대한 활용하기 위한 아키텍처이다.

 

 - HTTP URI를 통해 리소스를 명시하고, HTTP Method를 통해 해당 자원에 대한 동작을 명시하는 형식이다.

 

✅ REST API란?

 

 - 개발자들 사이에서 널리 이용되는, REST 형식을 따르는 API

 

 - 기계와 기계가 인터넷 또는 웹으로 통신할 수 있게 (즉, 정보를 주고받을 수 있게) 해주는 규격화된 통신 규칙.

 

 - 웹 서버의 리소스를 뷰페이지로 보여주는 대신 데이터 형태로 반환하므로,

    클라이언트의 종류에 상관 없이 웹 서버의 리소스를 사용하게 해준다.

 

 - 반환되는 데이터는 주로 XML이나 JSON 형태이다. (요즘에는 대부분 JSON)

 

 - 각 요청이 어떤 동작이나 정보를 위한 요청인지 , 즉 요청의 목적을 요청 주소(URL)의 모양만 보고 파악 가능하다는 것이 큰 특징이다!

 

 

 - REST API는 HTTP 규약을 따른다. ( ▶️ HTTP 관련 포스팅 보러가기 )

 - HTTP에는 각 목적에 따른 요청을 보내기 위한 다양한 메소드들이 있다.

 - REST API에서는 CRUD의 각 목적에 따라 아래 메소드들을 주로 활용한다.

 

목적(기능)	HTTP 메소드
Create	POST
Read	GET
Update	PUT (전체 내용 변경) PATCH (부분 변경)
Delete	DELETE

 

* 정리하면

    REST란, HTTP 요청을 보낼 때 어떤 URI에 어떤 메소드를 사용할지 명시하는 형식이다.

    REST API란, REST 형식을 따르는 API이다.

 

---

✅ REST API 설계 규칙

 

 - REST API의 자원 표현을 위한 URI 설계 규칙이 존재한다.

 

 -  아래의 설계 규칙들에 따라 URI를 설계하는 것이 좋다.

 

 

    ✏️ 소문자만 사용한다 (URI는 대소문자를 구분하므로, 혼동을 줄이기 위해서)

 

    ✏️ 언더바(_) 대신 하이픈(-)을 사용한다

 

    ✏️ 긴 URI에서 가독성을 높이기 위해 하이픈(-)을 사용해야 한다

http://catromi.tistory.com/v1/posts/thisismyfirstpost # ❌ 잘못된 예

http://catromi.tistory.com/v1/posts/this-is-my-first-post # 🟢 좋은 예

 

    ✏️ 확장자를 표시하지 않는다

http://catromi.tistory.com/v1/bear.jpg	# ❌ 잘못된 예

http://catromi.tistory.com/v1/bear	# 🟢 좋은 예

 

    ✏️ 맨 뒤에 슬래시(/)를 포함하지 않는다. 슬래시는 계층 관계를 나타낼 때만 사용해야 한다.

 

    ✏️ 행위를 포함하지 않는다

GET http://catromi.tistory.com/v1/get/1	# ❌ 잘못된 예

GET http://catromi.tistory.com/v1/1	# 🟢 좋은 예

 

    ✏️ 리소스에는 형용사나 동사가 아닌 명사를 활용한다. (컨트롤 자원을 의미하는 경우에만 예외적으로 동사를 사용한다)

http://catromi.tistory.com/getUsers # ❌ 잘못된 예

http://catromi.tistory.com/users # 🟢 좋은 예

 

    ✏️ URI에서는 항상 단수형 대신 복수형을 사용하도록 한다.

http://api.college.com/students/3248234/course # ❌ 잘못된 예

http://api.college.com/students/3248234/courses # 🟢 좋은 예

 

 

---

✅ Reference

• https://www.youtube.com/watch?v=PmY3dWcCxXI 
• https://www.youtube.com/watch?v=iOueE9AXDQQ&t=322 
• https://dzone.com/articles/7-rules-for-rest-api-uri-design-1