RESTful API

API

💡 API란 Application Programming Interface의 약자로 프로그램을 실행하는 인터페이스이다

• API를 통해 프로그램에 요청을 전달하기 위한 통로 혹은 방법이다.
• 라이브러리를 설치하고 호출하는 함수도 API이다.

 

REST API

💡 REST는 REpresentational State Transfer라는 용어의 약자로 HTTP method별로 역할 명시한 API

REST API 디자인 가이드

1. URL은 정보의 자원을 표현해야 한다.
   1. 정보의 자원 이름은 동사보다 명사를 사용한다.
   2. /members/1
2. 자원의 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)로 표현
3. GET /members/1

URL 설계 시 주의할 점

1. 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용한다.
2. URL 마지막 문자로 슬래시(/)를 포함하지 않는다.
3. 하이픈(-)은 URL 가독성을 높이는데 사용한다.
   1. 불가피하게 긴 URL 경로를 사용한다면 하이픈을 사용해 가독성을 높일 수 있다.
4. 밑줄(_)은 URL에 사용하지 않는다.
   1. 밑줄은 보기 어렵거나 밑줄 때문에 문자가 가려지는 경우가 있기 때문에 밑줄보다는 하이픈을 사용하는 것이 좋다
5. URL경로에는 소문자가 적합하다.
   1. RFC 3986(URL 문법 형식)은 URL 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정
6. 파일 확장자는 URL에 포함시키지 않는다.
   1. Accept header를 사용하여 파일 명시
   2. GET /members/soccer/245/photo HTTP/1.1 Host: restapi.example.com Accept: imgae/jpg

자원을 표현하는 Collection과 Document

💡 Document : 문서 혹은 객체 (단수로 표현)
     Collection : 문서들의 집합 혹은 객체들의 집합 (복수로 표현)

HTTP 상태 코드

• 200 : 클라이언트의 요청을 정상적으로 수행
• 201 : 클라이언트가 어떠한 리소스 생성을 요청, 해당 리소스가 성공적으로 생성됨 (POST를 통한 리소스 생성 작업 시)
• 400 : 클라이언트의 요청이 부적절 할 경우 사용하는 응답 코드
• 401 : 클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 때 사용하는 응답 코드
  • ex) 로그인 하지 않은 유저가 로그인 했을 때, 요청 가능한 리소스를 요청했을 대
• 403 : 유저 인증 상태와 관계 없이 응답하고 싶지 않은 리소스를 클라이언트가 요청했을 때 사용하는 응답 코드
  • 403 보다는 400이나 404를 사용할 것을 권고. 403 자체가 리소스가 존재한다는 의미 내포
• 405 : 클라이언트가 요청한 리소스에서는 사용 불가능한 메소드를 이용했을 경우 사용하는 응답 코드
• 301 : 클라이언트가 요청한 리소스에 대한 URL이 변경되었을 때 사용하는 응답 코드
  • 응답 시 Location header에 변경된 URL을 적어줘야 한다
• 500 : 서버에 문제가 있을 경우 사용하는 응답 코드

 

CRUD vs REST

CRUD

CRUD는 CREATE, READ, UPDATE, DELETE의 약자로, 데이터 베이스 응용프로그램에서 실행되는 네 가지 기본 작업을 나타내는 데 사용되는 약어

REST

REST는 클라이언트와 서버 간의 HTTP 프로토콜 인터페이스를 표준화하기 위해 만들어진 웹 API에서 널리 사용되는 디자인 스타일 중 하나

REST와 CRUD의 유사점

	REST	CRUD
데이터베이스에 새 레코드 생성	POST	CREATE	insert 문을 통해 새 레코드 생성
데이터베이스에서 가져온 정보를 읽기	GET	READ/RETRIEVE	입력 매개변수를 기반으로 데이터를 가져옴
개체를 업데이트	PUT/PATCH	UPDATE	데이터를 덮어쓰지 않고 업데이트
데이터베이스에서 레코드 제거	DELETE	DELETE	데이터 제거

REST와 CRUD의 차이점

• CRUD는 데이터베이스 설정에서 영구적인 기록을 하기 위한 주기이고, RESTful 아키텍처의 목표를 준수하기 위해 REST 명령에 매핑 된다
• 즉 REST api는 표준이고, CRUD는 함수이다.

 

출처

[04] CRUD vs REST 무슨 의미인가?

개발 초보를 위한 RESTful API 설계 가이드