Restful API

이미지 출처 : https://www.cloudways.com/blog/comprehensive-introduction-rest-api/

Restful API?

Restful API는 API 시스템을 구현하기 위한 아키텍처 중에 가장 널리 사용되는 형식
장점은 self-descriptiveness 자기 표현력이 높아서, 딱 보면 어떤 역할을 하는지 알 수 있다는 점

웹상에서 사용되는 여러 리소스를 HTTP URI로 표현하고 그 리소스에 대한 행위를 HTTP
Method로 정의하는 방식. 즉, 리소스(HTTP URI로 정의된)를 어떻게 한다(HTTP Method + Payload)를 구조적으로 깔끔하게 표현한 것.

기본 배경 지식

• URI : 해당 사이트의 특정 자원의 위치를 나타내는 유일한 주소 (URI와 URL의 차이)
• HTTP Method : HTTP request가 의도하는 action을 정의한 것(GET, POST 등)
• Payload : HTTP request에서 server로 보내는 데이터 (body)

RESTful API 디자인 가이드

RESTful API 설계 시 가장 중요한 항목 2가지.

첫 번째, URI는 정보의 자원을 표현해야 한다.
두 번째, 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

설계 규칙

1. URI는 정보의 자원을 표현해야 한다. (리소스명은 동사보다는 명사를 사용)

   GET /users/show/1 ㅡ> GET /users/1

• user/users, 단수/복수 사용은 회사마다 다르다. 요즘은 복수를 많이 사용하는 추세
• signup, signin 등은 보편적으로 많이 사용하기 때문에 허용된다.

2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)로 표현한다.

   GET delete/users/1ㅡ> DELETE /users/1
GET /members/insert/2 ㅡ> POST /members/2

3. resource 사이에 연관 관계가 있는 경우는 /리소스명/리소스ID/관계 있는 리소스 형식으로 나타낸다.

   GET /users/{user_id}/profile

HTTP Method

GET : 어떤 리소스를 조회할 때 사용
POST : 어떠 리소스를 생성할 때 사용.
PUT(PATCH) : 어떠 리소스를 갱신할 때 사용.
DELETE : 어떠 리소스를 삭제할 때 사용.

상태코드

2XX Success

200 OK
클라이언트의 요청을 서버가 정상적으로 처리할 경우 사용하는 응답코드

201 Created
클라이언트의 요청을 서버가 정상적으로 처리했고 새로운 리소스가 생길 경우 사용하는 응답코드
(POST, PUT을 통한 리소스 생성 작업)

204 No Content
클라이언트의 요청은 정상적이지만 컨텐츠를 제공하지 않을 경우 사용하는 응답코드
(DELETE를 통한 삭제 작업)

4XX Client errors

400 Bad Request
클라이언트의 요청이 부적절 할 경우 사용하는 응답 코드

401 Unauthorized(인증)
클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 때 사용하는 응답 코드
(로그인 하지 않은 유저가 로그인 했을 때, 요청 가능한 리소스를 요청했을 때)

403 Forbidden(권한)
유저 인증상태와 관계 없이 응답하고 싶지 않은 리소스를 클라이언트가 요청했을 때 사용하는 응답 코드

404 Not Found
클라이언트가 요청한 자원이 존재하지 않다.

405 Method Not Allowed
클라이언트가 요청한 리소스에서는 사용 불가능한 Method를 이용했을 경우 사용하는 응답 코드
상태코드

409 Conflict
클라이언트의 요청이 서버의 상태와 충돌이 발생한 경우 사용하는 응답코드
해당 요청의 처리 중 비지니스 로직상 불가능하거나 모순이 생긴 경우

5XX Server errors

5XX 상태 코드들은 서버 오류로 인해 요청을 수행할 수 없다는 의미

path parameter & query parameter

만약 어떤 resource를 식별하고 싶으면 path parameter를 사용하고,
정렬이나 필터링을 하는 경우에는 query parameter를 사용하는 것이 좋다.

query parameter를 사용하는 경우

1. 검색할 때(Searching), 조건을 줄 때(filtering)
   ?category=1&color=1

   • URL은 &가 and 인지 or 인지 정할 수 없다. 백 로직에서 결정한다.
   • 이상, 이하를 표현하기 위해 >, < 등의 연산자를 사용할 수 없다. 대신 ?price_bottom=3000 이런 식으로 3000원 이상을 나타낼 수 있따.

2. 정렬할 때(Sorting)
   ?order='max_price'

3. 페이지네이션
   ?offset=0&limit=100

   • 보통은 전체 count도 같이 보내준다.

query parameter 적용 예시

카테고리별 상품을 보여주고 싶을 때(filtering)

# product/views.py
class ProductView(View):
    def get(self, request):
        category = request.GET.get('category', None)

        products = Product.objects.all()

        if category:
            products = Product.objects.filter(category=category)
        
        product_list = [{
            'id': product.id,
            'name': product.name,
            (...생략)
            } for product in products
        ]
        return JsonResponse({'data': product_list}, status=200)

# 프로젝트명/urls.py
from django.urls import path, include

urlpatterns = [
    path('products', include('product.urls'))
]

# product/urls.py
from django.urls import path
from .views import ProductView

urlpatterns = [
    path('', ProductView.as_view()),
]

# Httpie 통신
http -v GET 127.0.0.1:8000/products category==1

참고사이트
https://meetup.toast.com/posts/92
https://sanghaklee.tistory.com/61