TIL: 20 [API] RESTful API

kyung-baa·2022년 6월 25일
0
post-thumbnail

REST하다는 것은 무엇일까

REST(REpresentational State Transfer)

Representational State Transfer의 약자
자원(URI), 행위(HTTP Method), 표현(Representations)로 구성되어 있다.
현재 상태를 나타내면서 전달한다.
웹에 존재하는 모든 자원(resource, ex. 이미지, 동영상, 데이터)에 고유한 URI를 부여하여 자원에 대한 주소를 지정하는 방법론, 또는 규칙입니다. 현재 가장 널리 사용되고 있다.

장점: self-descripiveness, Restfull API는 그 자체만으로도 API의 목적이 쉽게 이해가 된다.
단점: 표준 규약이 없어, 안티패턴으로 작성되는 경우가 흔하다.
안티패턴: 실제 사용되는 패턴이지만 비효율적이거나 비생산적인 패턴

REST API URI를 결정하는 몇가지 규칙

1. 소문자를 사용한다

대문자는 때로 문제를 일으키는 경우가 있기 때문에 URI를 작성할 때는 소문자를 선호한다.

RFC3986은 체계 및 호스트 구성요소를 제외하고 URI를 대소문자를 구분하여 정의한다.

BAD
http://api.example.com/firstProject

GOOD
http://api.example.com/first-project

2. 언더바대신 하이픈을 사용한다.

가독성을 위해 긴 Path를 표현하는 단어는 하이픈으로 구분하는 것이 좋다.

프로그램의 글자 폰트에 따라서 언더바 문자는 문자가 부분적으로 가려지거나 숨겨질 수 있다. 혼란을 야기할 수 있으므로 하이픈을 사용한다.

BAD
http://api.example.com/blogs/guy-levin/posts/this_is_my_first_post

GOOD
http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post

3. URI의 마지막에는 슬래시를 포함하지 않는다.

후행 슬래쉬는 의미가 전혀 없고 혼란을 야기할 수 있다.

많은 웹 구성 요소와 프레임워크는 다음 두 URI를 동등하게 취급한다.
http://api.canvas.com/shapes/
http://api.canvas.com/shapes
그러나 URI내의 모든 문자는 리소스의 고유 ID에 포함된다.
두 개의 다른 URI는 두개의 다른 리소스에 매핑된다. URI가 다르면 리소스도 다르고 그 반대도 마찬가지다. 그러므로 REST API는 명확한 URI를 생성해야한다.

BAD
http://api.canvas.com/shapes/

Good
http://api.canvas.com/shapes

4. 계층관계를 나타낼 때는 슬래시 구분자를 사용해야한다.

슬래시 문자는 URI의 경로 부분에서 자원 간의 계층적 관계를 나타내기 위해 사용한다.
행위는 포함하지 않는다.
행위는 URL대신 Method를 사용하여 전달한다.

Bad
http://api.college.com/get-students

Good
http://api.college.com/students/

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

파일 확장자는 URI에 포함하지 말아야한다. 대신에 Content-Type 이라는 헤더를 통해 전달되는대로 미디어 타입을 사용하여 body의 콘텐츠를 처리하는 방법을 결정한다.

Rest API클라이언트는 HTTP에서 제공하는 형식 선택 메커니즘인 Aceept 요청 헤더를 활용하도록 권장해야 한다.

Bad
http://api.college.com/students/3248234/courses/2005/fall.json

Good
http://api.college.com/students/3248234/courses/2005/fall

6. 전달하고자 하는 자원의 명사를 사용하되, 컨트롤 자원을 의미하는 경우 예외적으로 동사를 허용한다.

BAD
http://api.college.com/course/writing

GOOD
http://api.college.com/course/write

7. URI에 작성되는 영어를 복수형으로 작성한다.

하나의 인스턴스를 복수형으로 표시하는게 영어 문법적으로 맞지 않겟다고 생각할 수도 있지만 URI의 형식을 복수형으로 사용하는 것이 실무에서 많이 사용되고 있다.
관계가 다른 리소스 내에서만 존재할 경우 RESTFUL 원칙은 다음과 같은 지침을 제공한다.
http://api.college.com/students/3248234/courses
ID가 3248234인 학생이 학습한 모든 과정 목록 검색 http://api.college.com/students/3248234/courses/physics
ID가 3248234인 학생을 위한 과정 물리학을 검색한다.

 깔대기 꼽듯이 상위 개념에서 하위 개념으로 이동하면서 사용하자

Path parameter



삭제 성공 > 삭제했기 때문에 없다는 내용의 응답이 왔음

Query parameter

? 뒤에 내가 원해는 내용이 key value로 들어온다.
예시 1 가격이 삼천원인 애들만 불러옴
예시 2 가격 삼천원 이름 사과인 애들만 불러옴


-를 붙이면 순서의 재배열 (리스트에서 최근 등록순 좋아요 순 등등 정렬)

100개씩 보기
offset 출발점 limit 마지막
Next, previous 로 다음에 불러오는 데이터 양을 짐작할 수 있다.

3번에 대한 내용을 간단하게 불러오는 거라서 패스 파라미터 사용
그 정보가 양이 적다면 패스 파라미터 (네트워크 통신 상 최대한 불필요한 부분은 없애는 게 좋다)

profile
나는야 경바

0개의 댓글