[HTTP/네트워크] 실습 - REST API

Hyun Jin·2023년 1월 31일
REST APIhttp네트워크
0

1. REST API 디자인

1-1. REST (Representational State Transfer) API

REST API 의 정의

  • 웹에서 사용되는 데이터나 자원(Resource)에 HTTP URI(고유한 ID 역할)을 부여하고, 해당 자원의 상태(정보)를 HTTP 프로토콜을 통해 request - responce 하는 방식을 정해놓은 아키텍처의 한 형식.
  • restful 한 방식으로 클라이언트와 서버 간 상호 데이터 교환을 하는 웹 API나 웹 서비스. 서로 stateless 한 특징이 있음

REST 의 구성요소

  1. 자원(Resource) - URI 로 자원의 위치에 접근함 (자원을 구별하는 고유한 ID 로 HTTP URI를 사용)
  2. 행위(Verb) - Http Method (GET, POST, PUT, DELETE)
  3. 표현(Representations) - Client 가 자원의 상태(정보) 조작 요청 -> Server 에서 응답(Representation)을 보냄.
    자원은 JSON, XML, TEXT, RSS 등 여러 형태의 Representation 으로 나타낼 수 있으나, 대부분 JSON 으로 주고받음.

URI 설계 시 지켜야 할 규칙

  1. 슬래시 구분자 ( / )는 계층 관계를 나타내는데 사용한다.

  2. URI 마지막 문자로 슬래시 ( / )를 포함하지 않는다.
    즉 URI에 포함되는 모든 글자는 리소스의 유일한 식별자로 사용되어야 하며 URI가 다르다는 것은 리소스가 다르다는 것
    역으로 리소스가 다르면 URI도 달라져야 한다.

  3. 하이픈 ( - )은 URI 가독성을 높이는데 사용한다.

  4. 밑줄 ( _ )은 URI에 사용하지 않는다.

  5. URI 경로에는 소문자가 적합하다.
    URI 경로에 대문자 사용은 피하도록 한다.

  6. 파일확장자는 URI에 포함하지 않는다.
    REST API 에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다.
    대신 Accept Header 를 사용한다.
    ex) GET: http://restapi.exam.com/orders/2/Accept: image/jpg

  7. 리소스 간에 연관 관계가 있는 경우
    /리소스명/리소스ID/관계가 있는 다른 리소스 명
    ex) GET: /users/2/orders (일반적으로 소유의 관계를 표현할 때 사용)

Endpoint

  • 같은 URI에 대해서도 메소드에 따라 다른 요청을 할 수 있게 구별해주는 항목.
  • An Endpoint URL. An application implementing a RESTful API will define one or more URL endpoints with a domain, port, path, and/or query string — for example,
    https://mydomain/user/1 =>
    GET /mydomain/user/1
    POST /mydomain/user/1
    DELETE /mydomain/user/1

REST의 6가지 원칙(특징)

1. 클라이언트 / 서버 구조

클라이언트는 유저와 관련된 처리를, 서버는 REST API를 제공함으로써 각각의 역할이 확실하게 구분되고 일괄적인 인터페이스로 분리되어 작동할 수 있게 한다
REST Server: API를 제공하고 비지니스 로직 처리 및 저장을 책임진다.
Client: 사용자 인증이나 context (세션, 로그인 정보) 등을 직접 관리하고 책임진다.
서로 간 의존성이 줄어든다.

2. 무상태성 (Stateless)

REST는 HTTP의 특성을 이용하기 떄문에 무상태성을 갖는다.
즉 서버에서 어떤 작업을 하기 위해 상태정보를 기억할 필요가 없고 들어온 요청에 대해 처리만 해주면 되기 때문에 구현이 쉽고 단순해진다.

3. 캐시 처리 가능 (Cacheable)

HTTP라는 기존 웹표준을 사용하는 REST의 특징 덕분에 기본 웹에서 사용하는 인프라를 그대로 사용 가능하다.
대량의 요청을 효율적으로 처리하기 위해 캐시가 요구된다.
캐시 사용을 통해 응답시간이 빨라지고 REST Server 트랜잭션이 발생하지 않기 때문에 전체 응답시간, 성능, 서버의 자원 이용률을 향상시킬 수 있다.

4. 자체 표현 구조 (Self - descriptiveness)

JSON을 이용한 메시지 포멧을 이용하여 직관적으로 이해할 수 있고 REST API 메시지만으로 그 요청이 어떤 행위를 하는지 알 수 있다.

5. 계층화 (Layered System)

클라이언트와 서버가 분리되어 있기 때문에 중간에 프록시 서버, 암호화 계층 등 중간매체를 사용할 수 있어 자유도가 높다

6. 유니폼 인터페이스 (Uniform)

Uniform Interface는 Http 표준에만 따른다면 모든 플랫폼에서 사용이 가능하며, URI로 지정한 리소스에 대한 조작을 가능하게 하는 아키텍쳐 스타일을 말한다
URI로 지정한 Resource에 대한 조작을 통일되고 한정적인 인터페이스로 수행한다.
즉, 특정 언어나 기술에 종속되지 않는다.

🔗 참고 사이트 :
What Is a REST API?
RESTful API 이란
AWS - RESTful API란 무엇입니까?

1-2. REST API를 디자인하는 방법

* Leonard Richardson의 REST 성숙도 4단계 모델

REST 성숙도 모델 - 0단계 : HTTP

  • HTTP 프로토콜을 사용함.(REST API 를 작성하기 위한 기본 단계)
  • 해당 단계는 REST API가 아닌 HTTP API임
  • 요청에 대한 Endpoint : 구별되지 않음
  • HTTP Method : POST 메서드만 사용 (CRUD(Create, Read, Update, Delete)와 상관없이)

REST 성숙도 모델 - 1단계 : + Resources(Endpoint)

  • 1단계에서는 개별 리소스(Resource)와의 통신을 준수해야 함.
  • 모든 자원은 개별 리소스에 맞는 Endpoint 를 사용해야 하며, 요청하고 받는 자원에 대한 정보를 응답으로 전달해야 함.
  • +) Endpoint 작성 시 주의점 : 명사 형태의 단어로 작성(동사, HTTP 메서드, 어떤 행위에 대한 단어 사용 지양할 것)
  • HTTP Method : GET, POST 메서드만 사용 (CRUD(Create, Read, Update, Delete)와 상관없이)
  • StatusCode: 무조건 200으로 전달
  • 헤더에 Content-Type이나 Cache 관련 정보도 제공하지 않음

REST 성숙도 모델 - 2단계 : + HTTP Method + StatusCode

  • 2단계에서는 4가지 HTTP Method를 사용해서 CRUD를 표현하고, StatusCode(POST - 201 created 등)를 활용하여 응답코드를 반환함.
    ? - 관련 리소스를 클라이언트가 Location 헤더에 작성된 URI를 통해 확인할 수 있도록 하면 완벽하게 REST 성숙도 모델의 2단계를 충족함
  • HTTP 메서드의 역할 및 사용 시 유의할 규칙들 :
    GET : 요청한 data 가져오기 / 서버의 데이터를 변화시키지 않는 요청에 사용
    POST : 새로운 data 생성 / 요청마다 새로운 리소스를 생성(멱등성을 가지지 않음)
    PUT : 기존 data 대체(교체) / 요청마다 같은 리소스를 반환(멱등성(idempotent)을 가짐)
    PATCH : 기존 data 수정(업데이트)
    DELETE : 기존 data 삭제

  • POST vs PUT : 멱등성 유무에 주의.

  • PUT vs PATCH : 용도 구분에 주의(PUT=>교체, PATCH=>수정)

  • 멱등성(idempotent) : 해당 메서드가 동일한 요청을 한 번 보내는 것과 여러 번 연속으로 보내는 것이 같은 효과를 지니고, 서버의 상태도 동일하게 남는 것.(POST, PATCH 만 멱등성을 가지지 않음)

https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#74-supported-methods

🔗 참고 사이트 :
Microsoft/api-guidelines
MDN - Idempotent

REST 성숙도 모델 - 3단계 : + HATEOAS(Hypermedia Control)

  • HATEOAS(Hypermedia As The Engine Of Application State)라는 약어로 표현되는 하이퍼미디어 컨트롤을 적용
  • 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성(API 서비스의 모든 End-point를 최초 진입점이 되는 URI를 통해 Hypertext Link 형태로 제공)
  • 이때 응답에 들어가게 되는 링크 요소는 응답을 받은 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함
  • 응답 내에 새로운 링크를 넣어 새로운 기능에 접근할 수 있도록 하는 것이 3단계의 핵심 포인트

Open API

API Key

profile
Hyun Jin
새싹 프론트엔드 개발자
이전 포스트

[HTTP/네트워크] 기초

다음 포스트

[Web Server] 기초 - CORS, SOP

0개의 댓글