필요성

RESTful API

💡 RESTful API는 REST 원칙을 따르며, 자원을 표현하고 상태를 전송하기 위한 간단하고 표준화된 방법을 제공하는 인터페이스입니다.

1. What is.. “REST”?

REST는 Representational State Transfer로, 네트워크 상에서 Client와 Server 사이의 통신 방식 중 하나입니다.

1) HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고

2) HTTP Method(POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것.

• HTTP 프로토콜?

  HTTP는 클라이언트와 서버 간 통신을 위한 통신 규칙 세트(프로토콜).

  사용자가 웹 사이트를 방문하면 사용자 브라우저(마치 크롬과 사파리)가 웹 서버에 HTTP 요청을 전송하고, 웹 서버는 HTTP 응답으로 응답함.

  

  • HTTP vs HTTPS(Hypertext Transfer Protocol Secure) : 암호화를 포함하여 보다 안전한 버전!
  • HTTP의 작동 : GET (웹 사이트의 일부 데이터를 볼 때) / PUT (일부 정보를 입력? 전송할 때)

operation	HTTP method
Create (생성)	POST
Read (조회)	GET
Update (수정)	PUT
Delete (삭제)	DELETE
Head (header 정보 조회)	HEAD

• 자원(resource)과 표현(representation)
  • 자원 : 해당 소프트웨어가 관리하는 모든 것. 텍스트가 될 수도 있고, html이 될 수도 있다.
  • 자원의 표현 : 그 자원을 표현하기 위한 이름. ex) DB의 전화번호가 자원일 때, phonenumbers을 자원의 표현으로 정한다.
    
• URI (Uniform Resource Identifier) URI는 자원의 위치뿐만 아니라 자원에 대한 고유 식별자. URL보다 더 좁은 범위. ex) students가 학생 번호를 나타내는 자원의 표현이라면, URI는 다음과 같이 구성될 수 있다.
  

   🌐 http://education.co.kr/students/20


   위의 URI를 통해, `students`가 20인 자원을 식별하고 있는 것이다.

2. What is.. “RESTful”?

RESTful은 일반적으로 REST라는 아키텍처를 따르는 웹 서비스를 가리킵니다.

그렇다면, REST라는 웹 통신 방식을 따라서 얻는 이득은 무엇일까요..?

확장성

HTTP가 네트워크 통신의 표준으로 채택되어 있는데, RESTful API는 HTTP 프로토콜을 기반으로 하기 때문에, 어떤 플랫폼이든, 어떤 언어든 HTTP를 지원한다면 모두 사용할 수 있습니다. 이로써, 클라이언트와 서버 간의 상호 작용이 훨씬 간단하고 편리해집니다.

간결성과 가독성

RESTful API는 간단하고 직관적인 인터페이스를 제공합니다. HTTP 메서드(GET, POST, PUT, DELETE 등)를 사용하여 자원을 다루고, 자원은 고유한 URI를 통해 식별됩니다. 이로써 개발자들은 일관된 방식으로 리소스에 접근하고 조작할 수 있습니다.

경량성

데이터 포맷으로 JSON이 주로 사용되기 때문에 빠르고 효율적인 통신이 가능합니다. 이는 빠른 응답 시간을 제공하는 데 도움이 됩니다.

Swagger

Swagger 는 REST API를 설계, 빌드, 문서화 및 사용하는 데 도움이 되는 OpenAPI 사양을 중심으로 구축 된 오픈 소스 도구 세트입니다.

FastAPI에서, 자동으로 생성된 웹 속 API 문서를 본 적이 있지 않나요..?

그것이 바로, Swagger입니다.

Swagger를 사용해야 하는 이유는 단순합니다…👍

1. 적용하기 쉽기 때문에 or 떠먹기만 하면 되기 때문에..

   FastAPI가 아닌 다른 웹 프레임워크에서는 코드 몇 줄이면 Swagger UI를 생성할 수 있다고 합니다. 하지만 저번에 공부하였던 FastAPI의 경우, 자체적으로 이를 생성해주기 때문에 적용할 필요도 없이 그저 사용만.. 하면 됩니다.

2. 테스트 할 수 있는 UI를 제공하기 때문에

   Swagger UI에서는 직접 입력도 하여 설계한 대로 출력이 나오는 지 확인해 볼 수 있습니다. 굳이 html template을 만들어 연결하지 않아도 이 docs를 활용한다면, 웹을 통한 모델 데모 등을 쉽게 구현해볼 수 있는 것입니다.

기능적 특징

RESTful API 설계 규칙

1️⃣ HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고

2️⃣ HTTP Method(POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것.

위의 REST 내용을 참고하면서 이해해보도록 하자.

1. URI에 HTTP Method가 들어가면 안된다.

   ex) GET /members/delete/1 -> DELETE /members/1

2. URI에 행위에 대한 동사 표현이 들어가면 안된다.

   ex) GET /members/show/1 -> GET /members/1

   ex) GET /members/insert/2 -> POST /members/2

3. 경로 부분 중 변수는 유일한 값으로 대체한다.

   ex) id=12인 student를 삭제하는 route: DELETE /students/12

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

   ex) http://skku.edu/aai/lab/dsail

5. URI 마지막 문자로 슬래시(/)를 포함하지 않는다.

   ex) http://skku.edu/aai/lab/dsail~~/~~

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

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

8. URI 경로에는 대문자보다 소문자를 사용하도록 한다.

9. 파일 확장자는 URI에 포함하지 않는다.

   ex) http://skku.edu/aai/lab/dsail/research/31/result.png

• RESTful or not?
  • CRUD 기능을 모두 GET으로만 처리하는 API ❌
    
  • route에 resource, id 외의 정보가 들어가는 경우(/dsail/showFeat) ❌
    

목적

• 이해하기 쉽고, 사용하기 쉬운 API를 만들자!
• API의 이해도 및 호환성을 높이자!

Swagger UI에서 할 수 있는 것들

• 구성
  

  API라는 리모콘이 있다면, 각 리모콘의 버튼 기능을 설명해 놓은 문서를 제공해주는 기능을 한다고 보면 된다. 각 url이 입력되었을 때, 어떠한 HTTP Method(POST, GET, PUT, DELETE)가 실행되는지 확인할 수 있습니다.
  

• API 테스트 → 입/출력 가능

  • 예시) Stable Diffusion text-to-image 모델을 다룬 웹 애플리케이션

    

    프롬프트 입력하는 모습

    

    결과가 출력된 모습

    FastAPI for Machine Learning: Live coding an ML web application.
    

sample code

swagger

• 웹 화면 (http://127.0.0.1:8001)

  

• 실행 코드

  from typing import Union
  from fastapi import FastAPI
  
  app = FastAPI()
  
  @app.get("/")
  def read_root():
      return {"Name": "ShinYeeun"}
  
  @app.get("/items/{item_id}")
  def read_item(item_id: int, q: Union[str, None] = None):
      return {"item_id": item_id, "q": q}

  • read_root() : root url을 입력하였을 때 해당 딕셔너리를 반환한다.
  • read_item() : item_id와 q 값을 가져와 그에 대한 딕셔너리를 반환한다.

• Swagger UI (http://127.0.0.1:8001/docs)

  

  전체적인 화면

  

  Swagger UI에서 입력 테스트하는 모습

  

  실제로 입력된 값이 웹에 띄워지는 듯 보인다.
  

Reference

필요성

• https://hahahoho5915.tistory.com/54
• https://aws.amazon.com/ko/compare/the-difference-between-https-and-http/
• https://velog.io/@torang/URL과-URI의-차이점
• https://velog.io/@banjjoknim/Swagger

기능적 특징

• https://hahahoho5915.tistory.com/54#REST%--API%--�%--%A-�%B-%--%--�%B-%-C�%B-%--
• https://velog.io/@gimminjae/Swagger-UI란-왜-사용해야-할까
• https://swagger.io/tools/swagger-ui/