YeonBot

YeonBot

행복하게 살자

REST API 디자인

업데이트:

Web API 디자인

내용

  1. [REST 소개]

  2. [리소스를 중심으로 API 구성]

  3. [HTTP 메서드를 기준으로 작업 정의]

  4. [HTTP 의미 체계 준수]



REST 소개

  • 분산 시스템을 구축 하기 위한 아키텍쳐 스타일
  • Http 와 연결될 필요 없지만, 대부분 프로토콜로 Http 사용
RESTful API 디자인 원칙 / 특징

  • 리소스 중심의 디자인 , 클라이언트에서 액세스 할 수 있는 모든 종류의 개체 데이터 또는 서비스가 리스소에 포함.

  • 리소스 마다 해당 리소스를 고유하게 식별하는 URI(식별자) 존재.

  • 클라이언트가 리소스의 표현을 교환, 보통 교환 형식으로 JSON 사용

  • REST API는 균일한 인터페이스를 사용, 클라이언트와 서비스 구현을 분리하는 데 도움을 줌

  • HTTP를 기반으로 하는 REST API 의 경우 리소스에 표준 HTTP 동사 수행 작업을 사용(GET POST PUT DELETE… )

  • REST API는 상태 비저장 요청 모델 stateless

    HTTP요청은 독립적, 임의 순서 발생할 수 있다, 요청 사이에 일시적 상태 정보 유지 X



리소스를 중심으로 API 구성

  • API 가 표시하는 비즈니스 엔터티에 집중, 편지 보내기 서비스의 기본 엔터티, 편지 & 회원

  • HTTP POST 요청을 통해 편지를 보내기 가능.

  • HTTP 응답은 편지를 성공적으로 보냈는지 여부

  • 리소스 URI 는 동사(편지에 대한 작업)이 아닌 명사(리소스) 기반

  • https://phoneletter.com/users 	//Good

https://phoneletter.com/create-user // Avoid

  • 리소스는 단일 물리적 데이터 항목을 기반으로 할 필요 없다.

    데이터베이스의 여러 테이블, 내부 구조를 그대로 보여주는 API는 만들지 말라,

    클라이언트는 내부구현에 노출 되면 안된다.

  • URI 에 대한 일관적인 명명 규칙 적용

    https://phoneletter/com/users

    회원 정보에 대한 목록을 검색. -> 회원 정보 목록에 각각 고유의 URI 가 있다.

    항목의 URI에 대한 HTTP GET 요청은 해당 항목의 세부 정보를 반환.

    이렇게 하면 컬렉션을 참조하는 URI 에 대해 복수 명사를 사용 할 수 있다.

    ex) /users   // 회원 정보
ex) /users/{id}   // id번쨰 회원 세부 정보

  • 서로 다른 리소스 형식을 연결 하는 방법도 고려 해야함

    ex) /users/5/letters    //5번째 user의 모든 편지 목록
ex) /letters/10/user    //10번째 편지를 보낸 또는 받은 user ? users ?

    그러나 이 모델을 너무 많이 확장하면 구현이 어렵다.

    HTTP 릉받 메시지의 본문에 연결된 리소스에 대한 탐색 가능한 링크를 제공하는 방법이 더 좋다.

    KeyWord : HATEOAS

TIP) 리소스 URI 가 < /컬렉션/항목/컬렉션 > 보다 복잡하게 요구 하지 않는것이 좋다.

웹 요청이 웹 부하를 높인다. 요청이 많을 수록 부하가 커진다.

번잡한 Web API 를 피하도록 노력해야한다.



HTTP 메서드를 기준으로 작업 정의

HTTP 프로토콜은 요청에 의미 체계의미를 할당하는 다양한 메소드를 정의

  • GET. 지정된 URI에서 리소스의 표현을 검색
  • POST. 지정된 URI에 새 리소스를 생성 / 본문에 새 리소스 세부 정보 제공
  • PUT. 지정된 URI에 리소스를 만들거나 대체 / 본문에 만들, 업데이트할 리소스 지정
  • PATCH. 리소스의 부분 업데이트를 수행 / 본문은 적용할 변경 내용을 지정
  • DELETE. 지정된 URI 의 리소스 삭제

ex) 편지 보내기 서비스 간단 REST API

리소스 POST GET PUT DELETE
/users 새유저 만들기 모든 유저 검색 유저 대량 업데이트 모든 유저 제거
/users/1 Error 유저 1 세부 정보 유저 1 세부 정보업데이트 유저 1 제거
/users/1/letter 유저 1에 대한 편지 만들기 유저 1 의 모든 편지 검색 유저 1의 편지 대량 업데이트 유저 1의 모든 편지 제거

  • POST PUT PATCH 차이 구분

    • POST 요청은 리소스 생성, 서버는 새 리소스에 URI 할당 , 클라이언트에 URI 반환.

      POST 요청은 새 리소스를 만들지 않고 기존 리소스에 처리할 데이터를 보내는데 사용할 수도 있다.

    • PUT 요청은 리소스를 만들거나 또는 기존 리소스를 업데이트.

      PUT 요청은 컬렉션보다는 특정 고객 같은 개별 항목인 리소스에 가장 자주 적용

    • PATCH 요청은 기존 리소스에 부분 업데이트를 수행

    PUT 요청은 idempotent(멱등법칙) 여야 합니다. 클라이언트가 동일한 PUT 요청을 여러 번 제출하는 경우 그 결과가 항상 같아야 합니다(같은 값을 사용하여 같은 리소스가 수정되므로). POST 및 PATCH 요청이 반드시 idempotent가 된다는 보장은 없습니다.



HTTP 의미 체계 준수

미디어 유형
  • 클라이언트& 서버는 리소스 표현을 교환.

ex) POST 요청의 본문에는 만들 리소스를 표현 , FET요청에소는 응답 본문에 가져온 리소스의 표현이 포함 .

HTTP 프로토콜에서 형식은 MIME 유형이라고도 하는 미디어 유형을 사용하여 지정됩니다. 이진이 아닌 데이터의 경우 대부분의 Web API는 JSON(미디어 유형 = 애플리케이션/json) 및 XML(미디어 유형 = 애플리케이션/xml)을 지원합니다.

  • JSON 데이터를 포함한 요청의 예
POST https://phoneletter.com/letters HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 57

{"Id":1,"Email":"tjddus1109@gmail.com","font":"Open-Sans","receiveEmail":"Fizz@ Gmail.com"}
  • 서버에서 미디어 유형을 지원하지 않으면 HTTP 상태 코드 415(지원되지 않는 미디어 유형)를 반환

클라이언트 요청에는 클라이언트가 응답 메시지에서 서버로부터 받는 미디어 유형 목록을 포함하는 Accept 헤더가 포함될 수 있다.

GET https://phoneletter.com/letters/2 HTTP/1.1
Accept: application/json
  • 서버가 나열된 미디어 유형 중 어떤 것도 일치시킬 수 없는 경우 HTTP 상태 코드 406(허용되지 않음)을 반환.
GET 메서드
  • 성공적인 GET 메서드는 일반적으로 HTTP 상태 코드 200(정상)를 반환
  • 리소스를 찾을 수 없는 경우 메서드가 404(찾을 수 없음)를 반환
POST 메서드

  • POST 메서드는 새 리소스를 만드는 경우 HTTP 상태 코드 201(만들어짐)을 반환

    새 리소스의 URI는 응답의 Location 헤더에 포함

    응답 본문은 리소스의 표현을 포함

  • 클라이언트가 잘못된 데이터를 요청에 배치하면 서버에서 HTTP 상태 코드 400(잘못된 요청)을 반환

    응답 본문에는 오류에 대한 추가 정보 또는 자세한 정보를 제공하는 URI 링크가 포함될 수 있다.

PUT 메서드
  • PUT 메서드는 POST 메서드와 마찬가지로 새 리소스를 만드는 경우 HTTP 상태 코드 201(만들어짐)을 반환
  • 기존 리소스를 업데이트할 경우 200(정상) 또는 204(내용 없음)를 반환
  • 상황에 따라 기존 리소스를 업데이트할 수 없는 경우도 있다. 이 경우 HTTP 상태 코드 409(충돌)를 반환하는 방안을 고려
PATCH 메서드
  • 어떻게 쓰는지 아직 잘 모르겠다….
DELETE
  • 삭제 작업이 성공하면 웹 서버는 프로세스가 성공적으로 처리되었지만 응답 본문에 추가 정보가 포함되지 않았음을 나타내는 HTTP 204 상태 코드로 응답
  • 리소스가 없는 경우 웹 서버는 HTTP 404(찾을 수 없음)를 반환
비동기 작업

경우에 따라 POST, PUT, PATCH 또는 DELETE 작업을 완료 하는 데 시간이 오래 걸리는 처리가 필요할 수 있습니다. 처리 작업이 완료될 때까지 기다렸다가 클라이언트에 응답을 보내는 경우 허용되지 않는 수준의 대기 시간이 발생할 수 있습니다. 이 경우 비동기 작업을 수행하는 방안을 고려해 보아야 합니다. 요청 처리가 수락되었지만 아직 완료되지 않았음을 나타내는 HTTP 상태 코드 202(수락됨)를 반환합니다.

클라이언트가 상태 엔드포인트를 폴링하여 상태를 모니터링할 수 있도록 비동기 요청의 상태를 반환하는 엔드포인트를 표시해야 합니다. 202 응답의 Location 헤더에 상태 엔드포인트의 URI를 포함합니다. 다음은 그 예입니다.

HTTP/1.1 202 Accepted
Location: /api/status/12345



출처

https://docs.microsoft.com/ko-kr/azure/architecture/best-practices/api-design

댓글남기기

참고