RESTful API💡: REST API Design Rulebook

RESTful

RESTful의 의미
REST적이다, REST스럽다

그럼, REST는 무엇?

REST (Representational State Transfer)
위키 REST

RESTful API

• "restful api"란 Endpoint의 주소를 결정하는 패턴을 의미!
• 패턴은 "http 메소드이름/읽고자하는부분의명사"임!
• Restful api에서 endpoint의 주소에는 명사만 들어감!!!!
• 이런 패턴을 쓰는 이유는 일관성있는 주소를 만들기 위해서임!

  예)
  Post/user
  Get/user1
  Get/users
  Delete/user1!

---

REST API Design Rulebook

: Designing Consistent RESTful Web Service Interfaces

읽어봅시당

회사에서 장고로 날씨 정보를 제공하는 API를 작성하는 업무를 맡았다.
query string에 '하이픈(-)을 써야하나? 언더바(_)를 써야하나?' 의문이 들어서 구글링을 했는데.
구글 SEO이슈로 하이픈을 쓰라는 의견이 많았다.
그리고 위의 책을 소개하는 글을 발견했다.
국내서점에는 ebook없어서
아마존에서 kindle용 ebook으로 구매했다.
이제 읽어보자!

목차

1. Introduction
   Hello World Wide Web
   Web Architecture
   Web Standards
   REST API Design Rulebook
   REST APIs
   REST API Design
   Recap
2. Identifier Design with URIs
   URIs
   URI Format
   URI Authority Design
   Resource Modeling
   Resource Archetypes
   URI Path Design
   URI Query Design
   Recap
3. Interaction Design with HTTP
   HTTP/1.1
   Request Methods
   Response Status Codes
   Recap
4. Metadata Design
   HTTP Headers
   Media Types
   Media Type Design
   Recap
5. Representation Design
   Message Body Format
   Hypermedia Representation
   Media Type Representation
   Error Representation
   Recap
6. Client Concerns
   Introduction
   Versioning
   Security
   Response Representation Composition
   Processing Hypermedia
   JavaScript Clients
   Recap
7. Final Thoughts
   State of the Art
   Uniform Implementation
   Recap
   A. My First REST API

나만의 summary

Preface

• Representational State Transfer (REST)
• REST는 WWW이 어떻게 작동하는지 나타내는 기술적인 묘사
• REST Application Programming Interface (REST API)는 클라이언트가 시스템의 데이터와 함수들을 구성하는 리소스들에 접근할 수 있도록하는 웹서버의 종류

  A REST Application Programming Interface (REST API) is a type of web server that enables a client, either user-operated or automated, to access resources that model a system’s data and functions.
  Masse, Mark. REST API Design Rulebook (p. 4). O'Reilly Media. Kindle Edition.

Chapter 1. Introduction

1) Hello World Wide Web

• URI (Uniform Resource Identifier): 웹 문서에 유니크한 주소를 부여하는 문법
• HTTP (HyperText Transfer Protocol): 인터넷을 통해 컴퓨너가 커뮤니케이션할 수 있는 메시지 기반의 언어
• HTML (HyperText Mark-up Language): 문서들과 연관된 링크들을 포함하는 유용한 문서를 나타내는 것

  On August 6, 1991, on the Web’s first page, Berners-Lee wrote, The WorldWideWeb (W3) is a wide-area hypermedia information retrieval initiative aiming to give universal access to a large universe of documents.[10]
  Masse, Mark. REST API Design Rulebook (p. 10). O'Reilly Media. Kindle Edition.

2) Key constraints:

• Client-Server
  • separation of concerns
• Uniform Interface
  • Identification of resources
    • URI
  • Manipulation of resources through representations
    • "representation"은 리소스 자체가 아니라 "리소스와 interact하는 방식"을 의미
  • Self-descriptive message
  • Hypermeida as the engine of application state (HATEOAS)
• Layered System
• Cache
• Stateless
  • 클라이언트가 state에 대한 복잡성을 관리함으로써, 웹서버는 더 많은 클라이언트를 수용할 수 있게 됨
• Code-on-demand
  • 옵셔저널 함

3) Web Standards

4) REST

5) REST APIs

Chapter 2. Identifier Design with URIs

"a set of design rules for REST API URIs"

1) URI (Uniform Resource Identifier)

Tim Berners-Lee included a note about the opacity of URIs in his “Axioms of Web Architecture” list:

The only thing you can use an identifier for is to refer to an object.
When you are not dereferencing, 
you should not look at the contents of the URI string to gain other information. 
								— Tim Berners-Lee 

http://www.w3.org/DesignIssues/Axioms.html
Masse, Mark. REST API Design Rulebook (p. 22). O'Reilly Media. Kindle Edition.

2) URI format

The rules presented in this section pertain to the format of a URI. RFC 3986[19] defines the generic URI syntax as shown below:

URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]

Masse, Mark. REST API Design Rulebook (pp. 22-23). O'Reilly Media. Kindle Edition.

Rule 1. 계층 관계를 나타낼 때는 "/" 반드시 사용
Rule 2. URI에는 트레일링 슬러시("/") 사용 불필요
Rule 3. 하이픈("-")을 사용하면 URI 가독성이 증가됨
Rule 4. 언더스코어("_")는 URI에 사용하지 말 것
Rule 5. URI 경로에는 소문자가 더 선호됨
    - 도메인 이름은 대소문자 상관없는데
    - 도메인을 제외한 URI는 대소문자를 구분해용!

RFC 3986 defines URIs as case-sensitive except for the scheme and host components. For example:
(1) http://api.example.restapi.org/my-folder/my-doc
(2) HTTP://API.EXAMPLE.RESTAPI.ORG/my-folder/my-doc
(3) http://api.example.restapi.org/My-Folder/my-doc
(1) This URI is fine.
(2) The URI format specification (RFC 3986) considers this URI to be identical to URI #1.
(3) This URI is not the same as URIs 1 and 2, which may cause unnecessary confusion.
Masse, Mark. REST API Design Rulebook (p. 24). O'Reilly Media. Kindle Edition.

Rule 6. 파일 확장자는 URI 포함하지 말 것
   - REST API에서는 URI 파일 확장자를 표시하지 않아요
   - 파일이 어떤 종류의 파일인지는 HTTP의 Content-Type 헤더에서 미디어 타입을 통해 알려주지요!

3) URI Authority Design
네이밍 컨벤션 부분!

Rule 1. API를 위해서 일관적인 서브도메인 이름 사용할 것
Rule 2. 클라은 개발자 포털을 위해서 일관적인 서브도메인 이름 사용할 것

4) Resource Modeling

5) Resource Archetypes
1. Document
2. Collection : 서버가 관리하는 리소스들의 "디렉터리"
3. Store : 클라이언트 관리하는 리소스들의 "저장소"
4. Controller : 함수처럼 인풋과 아웃풋이 있음
"store하고 controller의 개념 아리송송하다 -_-"

6) URI Path Design
Rule 1. 컬렉션 이름으로는 복수를 사용할 것
Rule 2. 스토어 이름으로는 복수를 사용할 것
Rule 3. 컨트롤러 이름으로는 동사/동사구 사용할 것
Rule 4. 변동이 있는 경로 세그먼트는 ID기반의 값으로 대체 가능
Rule 5. CRUD 기능이름은 URI에 사용하지 말 것

7) URI Query Design
Rule 1. URI의 쿼리 컴포넌트는 컬렉션 또는 스토어를 filter하는데 사용될 수 있음
Rule 2. URI의 쿼리 컴포넌트는 컬렉션 또는 스토어의 결과를 paginate하는데 사용될 수 있음

Chapter 3.

Reference

• https://www.amazon.com/-/ko/gp/product/B005XE5A7Q/ref=ppx_yo_dt_b_d_asin_image_o00?ie=UTF8&psc=1
• 생활코딩 Rest API
• User Timing API
• https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
• https://www.crummy.com/writing/speaking/2008-QCon/act3.html
• REST API Tutorial