Rest API

REST (Representational State Transfer)

설명

자원을 표현(Representational)으로 구분하여 해당 자원의 상태(State)를 주고 받는(Transfer)다.
HTTP URI(Uniform Resource Identifier)을 통해 자원(Resource)을 명시하고, Http Method(GET, POST, PUT, DELETE)을 통해 자원에 대한 CRUD Operation을 적용

✱ URI (Uniform Resource Identifier)
인터넷 자원을 나타내는 유일한 주소
scheme:[//[user[:password]@]host[:port]][/path][?query][#fragment]
 - URN: 자원의 이름 (식별자)
 - URL: 자원의 위치 

 

구성요소

1. 자원 (Resource)
‣ Http URI (ex. /users/:userId)

2. 행위 (Method)
‣ GET, POST, PUT, DELETE,
‣ HEAD (요청 header 정보만 응답),
‣ PATCH (PUT과 다르고, 자원의 일부만 수정하고자 할때 사용),
‣ OPTION (현재 End-point가 제공 가능한 API method를 응답)

3. 표현 (Representation of Resource)
  Client(브라우저)가 자원의 상태에 대한 조작을 요청(Request)하면 서버는 이에 적절한 응답(Response)을 보낸다.
  JSON, XML, TEXT, RSS 등 여러 형태로 표현

 

REST API 특징

1. 클라이언트/서버
‣ 아키텍처를 단순화 시키고 작은단위로 분리함으로써
클라이언트 - 서버 각 파트가 독립적으로 개선될 수 있도록 한다. 

2. 상태없음
‣ 클라이언트의 상태가 서버에 저장되어서는 안된다.

3. 레이어드 아키텍처 (Layered Architecture)
‣ 클라이언트 - 서버 연결 사이의 중간 서버가 존재하는 경우 (클라이언트 - 중간서버 - 서버),
중간서버(게이트웨이, 방화벽, 프록시 etc)는 로드밸런싱 혹은 공유 캐시 기능을 제공함으로써
시스템 규모 확장성을 향상시키는데 유용

4. 캐시 (Cache)
‣ 클라이언트 응답을 캐싱할 수 있어야 함. 캐싱함으로서 서버에 부하 최소화

5. 코드 온 디맨드(Code on demand)
‣ 요청이 오면 코드를 준다는 의미로 특정 시점에 서버가 특정 기능을 수행하는 스크립트 또는
플러그인을 클라이언트에 전달해서 해당 기능을 동작하도록 하는것. (자바스크립트, 플래시 etc)

6. 통합 인터페이스
‣ 일관적인 인터페이스로 분리 되어야 함.

 

REST 인터페이스 규칙

1. 리소스 식별
‣ 요청 내에 기술된 개별 자원을 식별할 수 있어야 한다. (URI)

2. 표현을 통한 리소스 처리
‣ 다양한 콘텐츠 유형으로 표현 가능 (JSON, XML, HTML ..)

3. 자기 묘사 메세지
‣ Http header 에 메타 데이터 정보를 추가해서 실제 데이터와는 관련 없지만
데이터에 대한 설명을 나타내는 정보를 담을 수 있음.

4. 어플리케이션의 상태에 대한 하이퍼미디어(HATEOAS, Hypermedia As The Engine Of Application State)
‣ REST API 개발할 때에 단순 데이터만 전달하지 않고, 링크 정보까지 포함하여 전달 (하이퍼 텍스트 링크)
‣ 리소스 상태가 전이되는 경우에 변경되는 정보를 제공하고자 함.
(등록 요청 후, 변경 된 정보를 좀 더 자세히 알고자 할때 하이퍼 링크도 같이 제공)
    

 

REST API 

설명

REST 아키텍처의 제약 조건을 준수하는 애플리케이션 프로그래밍 인터페이스

 

RESTful의 목적

API 이용자가 해당 API 으로 데이터를 얻고, 특정 기능을 파악할 수 있도록 하는 것

 

리소스 원형

도큐먼트 (document)
‣ 객체 인스턴스나 데이터베이스 레코드와 유사한 개념

컬렉션 (collection)
‣ 서버에서 관리하는 디렉터리 리소스 

스토어 (store)
‣ 클라이언트에서 관리하는 리소스 저장소
‣ API 클라이언트가 리소스를 등록/수정/삭제에 관여

컨트롤러 (controller)
‣ 절차적인 개념을 모델화 한 것

 

✰ REST API 디자인을 위한 규칙

추상적인 것 보단, 구체적인 것이 좋다.
ex) /animals -> /pigs

동사를 사용하지 않는다. (명사를 사용)
method 를 동사 대용으로 사용.

단수보단, 복수를 사용하는 것을 권장한다.
ex) /thing  ->  /things or /things/{id}

슬래시(/) 을 사용하여 계층관계를 표시해야 한다.
리소스간 연관관계는 /리소스명/리소스ID/관계가 있는 다른 리소스명 으로 표현한다.
ex) GET /users/{userid}/devices (소유자가 가지고있는 디바이스 목록?)

URL 마지막에 슬래시(/) 을 포함하지 않는다.
슬래시를 포함한다면, 슬래시 다음에 식별자가 와야하는데 오지 않음으로 혼동을 줄 여지가 있음.

URI의 가독성을 높히려면 하이픈(-)을 사용해야 한다.

URI에 밑줄(_)을 사용해선 안된다.
보기가 어려움. 가독성

URI 경로에는 소문자를 사용해야 한다.

파일 확장자는 사용하지 않는다.

 

---

참고

https://www.redhat.com/ko/topics/api/what-is-a-rest-api

(책) 스프링 부트로 배우는 자바 웹 개발

REST API(RESTful API, 레스트풀 API)란 - 서버, 구현, 사용법

https://nsinc.tistory.com/192

URL vs URI vs URN

https://spoqa.github.io/2013/06/11/more-restful-interface.html

RESTful API를 설계하기 위한 디자인 팁

https://dzone.com/articles/7-rules-for-rest-api-uri-design-1

7 Rules for REST API URI Design - DZone Integration

https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html

[Network] REST란? REST API란? RESTful이란? - Heee's Development Blog

https://www.slideshare.net/nexusz99/rest-api-48600643

REST API 디자인 개요

https://zsgg.tistory.com/entry/REST-API-%EB%94%94%EC%9E%90%EC%9D%B8-%EA%B7%9C%EC%B9%99

REST API 디자인 규칙

https://sanghaklee.tistory.com/57

RESTful API 설계 가이드

https://meetup.toast.com/posts/92

REST API 제대로 알고 사용하기 : NHN Cloud Meetup