Django REST Framework && RESTfull API

1. REST

• REST API는 리소스를 중심으로 디자인되며, 클라이언트에서 액세스할 수 있느 모든 종류의 개체, 데이터 또는 서비스가 리소스에 포함된다
• 리소스마다 해당 리소스를 고유하게 식별하는 URL인 식별자가 있다, 예를 들어 특정 고객 주문의 URI는 다음과 같다

// HTTP
https://adventure-works.com/orders/1

• 클라이언트가 리소스의 표현을 교환하여 서비스와 상호작용한다, 많은 Web API가 교환 형식으로 JSON을 사용, 예를 들어 위에 나열된 URI에 대한 GET요청은 이 응답 본문을 반환할 수 있다

//JSON
{"prderId" : 1, "orderValue":99.90, "productId":1, "quantity":1}

• REST API는 균일한 인터페이스를 사용하므로 클라이언트와 서비스 구현을 분리하는 데 도움이 됩니다. HTTP를 기반으로 하는 REST API의 경우 리소스에 표준 HTTP 동사 수행 작업을 사용하는 것이 균일한 인터페이스에 포함됩니다. 가장 일반적인 작업은 GET, POST, PUT, PATCH 및 DELETE입니다.
• REST API는 상태 비저장 요청 모델을 사용합니다. HTTP 요청은 독립적이어야 하고 임의 순서로 발생할 수 있으므로, 요청 사이에 일시적인 상태 정보를 유지할 수 없습니다. 정보는 리소스 자체에만 저장되며 각 요청은 자동 작업이어야 합니다. 이러한 제약 조건이 있기 때문에 웹 서비스의 확장성이 우수합니다. 클라이언트와 특정 서버 사이에 선호도를 유지할 필요가 없기 때문입니다. 모든 서버는 모든 클라이언트의 모든 요청을 처리할 수 있습니다. 그렇긴 하지만, 다른 요소가 확장성을 제한할 수 있습니다. 예를 들어 많은 웹 서비스가 백 엔드 데이터 저장소에 기록 하 여 확장 하기 어려울 수 있습니다. 데이터 저장소를 확장 하는 전략에 대 한 자세한 내용은 가로, 세로 및 기능 데이터 분할을 참조 하세요.
• REST API는 표현에 포함된 하이퍼미디어 링크에 따라 구동됩니다. 예를 들어 다음은 주문의 JSON 표현을 보여줍니다. 주문과 관련된 고객을 가져오거나 업데이트하는 링크를 포함하고 있습니다.

//JSON
{
    "orderID":3,
    "productID":2,
    "quantity":4,
    "orderValue":16.60,
    "links": [
        {"rel":"product","href":"https://adventure-works.com/customers/3", "action":"GET" },
        {"rel":"product","href":"https://adventure-works.com/customers/3", "action":"PUT" }
    ]
}

• 2008년에 Leonard Richardson은 Web API에 대한 다음과 같은 성숙도 모델을 제안했습니다.
• 수준 0: 한 URI를 정의합니다. 모든 작업은 이 URI에 대한 POST 요청입니다.
• 수준 1: 개별 리소스에 대한 별도의 URI를 만듭니다.
• 수준 2: HTTP 메서드를 사용하여 리소스에 대한 작업을 정의합니다.
• 수준 3: 하이퍼미디어(HATEOAS, 아래에 설명)를 사용합니다.
• 수준 3은 Fielding의 정의에 따르면 진정한 RESTful API에 해당합니다. 실제로 게시된 여러 Web API가 수준 2의 어딘가에 해당합니다.

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

-즉, 웹 API가 표시하는 비즈니스 엔터티에 집중해야 합니다. 예를 들어 전자 상거래 시스템에서는 기본 엔터티가 고객과 주문입니다. 주문 정보가 포함된 HTTP POST 요청을 전송하여 주문 만들기를 구현할 수 있습니다. HTTP 응답은 주문이 성공적으로 수행되었는지 여부를 나타냅니다. 가능하다면 리소스 URI는 동사(리소스에 대한 작업)가 아닌 명사(리소스)를 기반으로 해야 합니다.

 // HTTP
 https://adventure-works.com/orders // Good

https://adventure-works.com/create-order // Avoid

• 리소스 URI를 컬렉션/항목/컬렉션 보다 더 복잡하게 요구하지 않는 것이 좋습니다.

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

• GET 은 지정된 URI에서 리소스의 표현을 검색합니다. 응답 메시지의 본문은 요청된 리소스의 세부 정보를 포함하고 있습니다.
• POST 는 지정된 URI에 새 리소스를 만듭니다. 요청 메시지의 본문은 새 리소스의 세부 정보를 제공합니다. 참고로 POST를 사용하여 실제로 리소스를 만들지 않는 작업을 트리거할 수도 있습니다.
• PUT 은 지정된 URI에 리소스를 만들거나 대체(전체 Update)합니다. 요청 메시지의 본문은 만들 또는 업데이트할 리소스를 지정합니다.
• PATCH 는 리소스의 부분 업데이트를 수행(일부분)합니다. 요청 본문은 리소스에 적용할 변경 내용을 지정합니다.
• DELETE 는 지정된 URI의 리소스를 제거합니다.
  

4. HTTP 의미 체계 준수

• GET 메서드
  • 성공적인 GET 메서드는 일반적으로 HTTP 상태 코드 200(정상)를 반환합니다.
  • 리소스를 찾을 수 없는 경우 메서드가 4(찾을 수 없음)를 반환 합니다.
• POST 메서드
  • POST 메서드는 새 리소스를 만드는 경우 HTTP 상태 코드 201(만들어짐)을 반환합니다.
  • 새 리소스의 URI는 응답의 Location 헤더에 포함됩니다. 응답 본문은 리소스의 표현을 포함합니다.
  • 이 메서드가 일부 처리를 수행하지만 새 리소스를 만들지 않는 경우 메서드는 HTTP 상태 코드 200을 반환하고 작업의 결과를 응답 본문에 포함할 수 있습니다.
  • 또는 반환할 결과가 없으면 메서드가 응답 본문 없이 HTTP 상태 코드 204(내용 없음)를 반환할 수 있습니다.
  • 클라이언트가 잘못된 데이터를 요청에 배치하면 서버에서 HTTP 상태 코드 400(잘못된 요청)을 반환해야 합니다.
  • 응답 본문에는 오류에 대한 추가 정보 또는 자세한 정보를 제공하는 URI 링크가 포함될 수 있습니다.
• PUT 메서드
  • PUT 메서드는 POST 메서드와 마찬가지로 새 리소스를 만드는 경우 HTTP 상태 코드 201(만들어짐)을 반환합니다.
  • 이 메서드는 기존 리소스를 업데이트할 경우 200(정상) 또는 204(내용 없음)를 반환합니다.
  • 상황에 따라 기존 리소스를 업데이트할 수 없는 경우도 있습니다. 이 경우 HTTP 상태 코드 409(충돌)를 반환하는 방안을 고려해야 합니다.
  • 컬렉션의 복수 리소스에 대한 업데이트를 일괄 처리할 수 있는 일괄 HTTP PUT 작업의 구현을 생각해 보겠습니다.
  • PUT 요청은 컬렉션의 URI를 지정해야 하며, 요청 본문에 수정할 리소스의 세부 정보를 지정해야 합니다.
  • 이 접근 방식은 데이터 전송량을 줄이고 성능을 향상시킬 수 있습니다.
• PATCH 메서드
  • 클라이언트는 PATCH 요청을 사용하여 업데이트를 패치 문서 의 형태로 기존 리소스에 보냅니다.
  • 서버는 패치 문서를 처리하여 업데이트를 수행합니다.
  • 패치 문서는 리소스 전체가 아니라 적용할 변경 내용만 설명합니다.
  • PATCH 메서드에 대한 사양(RFC 5789)은 패치 문서에 대한 특정 형식을 정의하지 않습니다.
  • 형식은 요청의 미디어 형식에서 유추해야 합니다.
  • Web API에 대한 가장 일반적인 데이터 형식은 JSON일 것입니다.
  • 두 가지 주요 JSON 기반 패치 형식으로 JSON 패치 및 JSON 병합 패치 가 있습니다.
  • JSON 병합 패치는 비교적 간단합니다.
  • 패치 문서는 원래 JSON 리소스와 동일한 구조를 갖지만 변경 또는 추가할 필드의 하위 집합만 포함하고 있습니다.
  • 또한 패치 문서에서 필드 값에 대해 null을 지정하여 필드를 삭제할 수 있습니다. (즉, 원래 리소스가 명시적 null 값을 가질 수 있으면 병합 패치가 적합하지 않습니다.)
• DELETE 메서드
  • 삭제 작업이 성공하면 웹 서버는 프로세스가 성공적으로 처리되었지만 응답 본문에 추가 정보가 포함되지 않았음을 나타내는 HTTP 204 상태 코드로 응답해야 합니다.
  • 리소스가 없는 경우 웹 서버는 HTTP 404(찾을 수 없음)를 반환할 수 있습니다.
• 비동기 작업
  • 경우에 따라 POST, PUT, PATCH 또는 DELETE 작업을 완료 하는 데 시간이 오래 걸리는 처리가 필요할 수 있습니다.
  • 처리 작업이 완료될 때까지 기다렸다가 클라이언트에 응답을 보내는 경우 허용되지 않는 수준의 대기 시간이 발생할 수 있습니다.
  • 이 경우 비동기 작업을 수행하는 방안을 고려해 보아야 합니다.
  • 요청 처리가 수락되었지만 아직 완료되지 않았음을 나타내는 HTTP 상태 코드 202(수락됨)를 반환합니다.

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

5. Django REST framework

• API GUIDE
  • Views(JSON 작업)
  • Response(응답을 만들 수 있다, Django에서는 Rende와 같다(유사))
  • Serializers(Form, 데이터에 대한 검증, 모델에 있는 데이터를 전달할 수 있게끔 진열)
• 기본적으로 Django에서도 Json response를 제공(굳이 안써도 된다)
• 하지만 DRF를 사용하면 class based view로 클래스를 굳이 코드 작성안해도 화면 구현 가능

https://www.django-rest-framework.org/