REST API

https://rumbling-bear-8d2.notion.site/RESTful-API-API-a2c9507e91ff44b7aa032e5acffa3ac6

RESTful API (휴식스러운 API)

 

제가 직접 작성한 글입니다. 

 

REST API란?

사람들이 'REST API'라는 용어를 사용할 때 일반적으로 사전 정의된 URL 집합을 HTTP 프로토콜을 사용하여 API를 접근하는 것을 뜻합니다. 출처: How to Use Our REST APIs

 

• 깨알지식
  • 실제 REST는 하이퍼미디어에 기반한 분산 시스템을 만들기 위한 아키텍쳐 스타일. 고로 HTTP에 꼭 연관 되어 있지 않아도 됨.
  • 하지만 대부분 REST API는 HTTP protocol를 사용함.
• 역사
  • REST 이전엔 SOAP을 사용함.
  • 2000년도 “로이 필딩”이 박사 논문으로 “Architectural Styles andthe Design of Network-based Software Architectures” 발표함. 챕터 5에 REST 제약조건을 서술. 어떤 서버이든 아무 서버와 통신할 수 있도록 가능케 해주는 아키텍쳐.
  • 2000년 Salesforce라는 “Internet as a Service” 제품에 처음 도입함. 당시에는 XML기반으로 사용함.
  • 그 다음 eBay가 도입함. eBay가 도입 당시 자신들의 API를 접속할 수 있는 모든 웹사이트를 대상으로 시장을 확대함.
  • eBay로 인해 Amazon이 2002년도에 도입함.
  • Flickr가 2004년도 도입. REST API를 도입함으로써 블로거들이 자신들의 사이트에 쉽게 이미지를 embed 할 수 있도록 함.
  • 2006년 AWS가 AWS REST API를 도입하여 개발자들이 데이터 공간을 수분 내에 접근할 수 있도록 함.
  • 오늘날 REST API는 인터넷의 근간이 되었음.
  • 참고:
    • Fielding Dissertation: CHAPTER 5: Representational State Transfer (REST)
    • What is REST API (RESTful API)?
• REST의 장점
  • JSON/XML/HTML의 형식이면서, 경량, lightweight임.
  • 클라이언트와 서버의 독립
  • 확장성과 유연성
    • 서버/클라이언트의 독립으로 인해 확장이 용이함.
    • 개발자들은 추가 수고 없이 REST API를 자신들의 소프트웨어 도입할 수 있음.
  • 참고:
    • Top 3 benefits of REST APIs | MuleSoft
• SOAP vs REST
  • SOAP은 표준화 된 프로토콜
  • REST는 아키텍쳐 스타일

📌 REST API 설계 방법

• 리소스 중심으로 설계. 웹 API가 노출하는 비즈니스 엔티티에 집중
  • 리소스란?
    • API가 Client에게 제공하는 정보
• 리소스는 명사 중심, 동사 지양 (가능하면)
  • 예)
    • https://adventure-works.com/orders // Good
    • https://adventure-works.com/create-order // Avoid
• 구조는 collection/item/collection
  • /customers/1/orders
  • 이 계층 이상으로 넘어가는 것 지양.
  • /customers/1/orders/99 까지는 괜찮지 않을까 개인적으로 생각.
  • /customers/1/orders/99/products 이런 쿼리는
    • /customers/1/orders
    • /orders/99/products
    • 이렇게 나눠서 쿼리
• 내부 데이터베이스 구조를 그대로 API에 노출 지양
• 여러 리소스를 여러 request에 나누기 보다는 한번에 불러 올 수 있도록 설계. 단, overfetching은 피하기.
• 만약, API operation을 특정 리소스에 맵핑 할 수 없다면 query string 사용.
  • 예) GET 요청 /add?operand1=99&operand2=1
• Media types
  • JSON, XML (주로 JSON)

출처: Web API design best practices - Azure Architecture Center

일반적인 CRUD 형태

• HTTP Method 요청
• PUT vs PATCH
  • PUT:
    • item에 대한 전체 업데이트.
    • idempotent (멱등성: 연산을 여러번 적용하더라도 결과가 달라지지 않음.)
  • PATCH:
    • item에 대한 부분 업데이트. * PATCH도 item에 대한 전체 업데이트 가능.
    • idempotent (멱등성 보장하지 않음.)

출처:Web API design best practices - Azure Architecture Center

LIST, 페이지, 검색 필터등에 대한 처리: Query String 으로 처리.

• 필터
  • /orders?minCost=n
• 페이징
  • /orders?limit=25&offset=50
• 디리미터 사용
  • /orders?fields=ProductID,Quantity.

출처: Web API design best practices - Azure Architecture Center

다중 항목 업데이트

• PATCH (recommended)
  • 1PATCH /group/users 2[ 3 { "id": "userId1", "sequence": "newSequenceNumber1" }, 4 { "id": "userId2", "sequence": "newSequenceNumber2" }, 5 (...) 6]
• POST
  • header approach
  • 1POST /group/users 2X-Action: renumbering 3[ 4 { "id": "userId1", "sequence": "newSequenceNumber1" }, 5 { "id": "userId2", "sequence": "newSequenceNumber2" }, 6 (...) 7]
  • payload approach
  • 1POST /group/users 2{ 3 "action": "renumbering", 4 "list": { 5 [ 6 { "id": "userId1", "sequence": "newSequenceNumber1" }, 7 { "id": "userId2", "sequence": "newSequenceNumber2" }, 8 (...) 9 ] 10 } 11}
  • 출처: Update an entire resource collection in a REST way
• Excel Import/Export
  • /api/report/xlsx - creating a report in a .xlsx format
  • /api/report/xls - same as above, but in a .xls format
    • 출처: How to Generate an Excel Report in a Spring Boot REST API with Apache POI and Kotlin
  • xls/xls-view/{xls-view-id}/render
    • 출처: https://www.midori-global.com/products/better-excel-exporter-for-jira/server/documentation/rest-api
• 기타 파일업로드
  • 아래 링크에서 “controller” 검색
  • Spring Boot 2 - File Upload and Download Rest API Tutorial
  • Spring Boot File Upload / Download Rest API Example
• Update시 Request와 Response Object가 달라질 경우의 처리
  • 객체의 처리
    • 공통객체:
      • 장점:
        • Server와 Client를 둘 다 “제어”를 하면 공통 객체를 써도 무방함. 단, 이럴 경우 SOLID의 “단일책임원칙”을 위배함.
      • 단점:
        • 객체가 request 혹은 response 상태인데 client가 알 수가 없음.
        • 어떤 필드 값이 세팅이 되어야 하는지 알 수가 없음. 필수값이 셋팅이 안되었을 수 있음.
    • Req/Res 별도의 객체:
      • 장점:
        • 클라이언트가 필요한 데이터만 포함하기 때문에, 클라이언트 입장에서 어떤 값을 제공해야 하는지 알 수 있음.
      • 단점:
        • 객체 수가 늘어남.
    • 결론:
      • 그러나 다수의 의견은 필요에 따른 객체를 따로 만들어주는 것을 선호한다고 함. 상황에 따라 적절히 쓰면 됨.
    • 참고:
      • http://link-intersystems.com/blog/2012/01/12/pros-and-cons-of-service-layer-designs/
      • WCF design - One Request and Response object or multiple?
  • Json Patch 사용
    • 출처: Using JSON Patch in Spring REST APIs | Baeldung
• ApiResponse는 대체 되어야 하는가? (HTTP Status CODE 사용?)
  • 상태코드를 마주하는 프로그래머가 대처 하기 용이함.
  • 일반적인 클라이언트가 결과를 일반적인 방법으로 대처할 수 있도록 해줌.
    • 출처:
      • Why and how HTTP responses' status code matter?
  • SEO에 영향을 줌. 400-500 에러가 많으면 ‘검색봇’이 이 웹사이트는 높은 수준의 웹사이트가 아니라고 판단하여 검색랭킹에 낮게 반영될 수 있음.
    • 출처:
      • A Complete Guide and List of HTTP Status Codes
  • HTTP 상태 코드 목록
    • HTTP 상태 코드 - HTTP | MDN
  • 결론:
    • Yolo는 HTTP Status Code가 필요 없을 수 있으나, 자체 웹/앱은 HTTP status code가 필요해보임.
    • 자체 웹/앱도 Yolo Server를 사용할 것을 고려해, 지금부터 HTTP status code를 도입하는 것을 추천.
• JSON 응답처리
• Exception처리
  • @RestControllerAdvice + @ExceptionHandler
    • Exception Class
      • 1@ResponseStatus(value = HttpStatus.NOT_FOUND) 2public class ResourceNotFoundException extends Exception{ 3 4 private static final long serialVersionUID = 1L; 5 public ResourceNotFoundException(String message){ 6 super(message); 7 } 8}
    • @RestControllerAdvice
      • 1 @RestControllerAdvice 2 public class MyRestControllerAdviceHandler { 3 4 @ExceptionHandler(ResourceNotFoundException.class) 5 public ResponseMsg resourceNotFoundException(ResourceNotFoundException ex) { 6 ResponseMsg resMsg = new ResponseMsg(ex.getMessage()); 7 return resMsg; 8 } 9 10}
  • 출처:
    • @RestControllerAdvice vs @ControllerAdvice
    • Error Handling for REST with Spring | Baeldung
    • Best Practices for REST API Error Handling | Baeldung
    • Error Handling with Spring REST
    • Guide to Spring Boot REST API Error Handling
• redirect처리
  • HTTP 상태 코드
    • 307: Temporary Redirection
      • 주의: 원본 HTTP action이 보존 되어야 함.
    • 308: Permanent Redirection
      • 주의: 새롭고 영구적인 URI를 사용할 때.
    • 출처: https://tools.ietf.org/id/draft-hunt-http-rest-redirect-00.html
  • Spring 구현법
    • HttpServletReponse
      • 1@RequestMapping("/foo") 2 void handleFoo(HttpServletResponse response) throws IOException { 3 response.sendRedirect("some-url"); 4 }
    • ResponseEntity
      • 1HttpHeaders headers = new HttpHeaders(); 2headers.setLocation(URI.create(newUrl)); 3return new ResponseEntity<>(headers, HttpStatus.MOVED_PERMANENTLY);
    • RedirectView
      • 1@RequestMapping("/foo") 2 public RedirectView handleFoo() { 3 return new RedirectView("some-url"); 4 }
    • 참조:
      • Spring MVC @RestController and redirect
      • Redirect to an external URL from controller action in Spring MVC

📌 REST API for REACT

• React.js and Spring Data REST
• https://betterprogramming.pub/rest-api-consumption-in-react-with-fetch-axios-and-axios-hooks-d9dd14b43c8b

참고자료:

• How to Use Our REST APIs
• REST API: Best Practices
• What is REST API design? | MuleSoft
• The Jira Cloud platform REST API
• What is REST - REST API Tutorial
• REST Resources
• [Resources](https://restful-api-design.readthedocs.io/en/latest/resources.html#:~:text=The fundamental concept in any,methods that operate on it.)
• REST API Design Best Practices Handbook – How to Build a REST API with JavaScript, Node.js, and Express.js
• Stripe Samples
• Tour of the API
• REST API: Key Concepts, Best Practices, and Benefits
• REST API | Home Assistant Developer Docs
• REST API Tutorial
• REST API (Introduction) - GeeksforGeeks
• Understanding And Using REST APIs — Smashing Magazine
• REST APIs: How They Work and What You Need to Know
• What is REST API (RESTful API)?
  • rest API 역사
• Using the REST API | REST API Handbook | WordPress Developer Resources
• https://aws.amazon.com/ko/what-is/restful-api/
• Fielding Dissertation: CHAPTER 5: Representational State Transfer (REST)
• https://www.amazon.com/REST-Practice-Hypermedia-Systems-Architecture/dp/0596805829/
• api-guidelines/Guidelines.md at vNext · microsoft/api-guidelines
• Rest API Documentation
• Web API design best practices - Azure Architecture Center