<div id="readability-page-1" class="page"><div><h2 id="-설계-중심-규칙"><a href="#-%EC%84%A4%EA%B3%84-%EC%A4%91%EC%8B%AC-%EA%B7%9C%EC%B9%99" aria-label=" 설계 중심 규칙 permalink"></a>📌 설계 중심 규칙</h2>
<blockquote>
URI는 정보의 자원을 표현해야 한다
자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)으로 표현한다
</blockquote>
<h2 id="uri-작성-규칙"><a href="#uri-%EC%9E%91%EC%84%B1-%EA%B7%9C%EC%B9%99" aria-label="uri 작성 규칙 permalink"></a>URI 작성 규칙</h2>
👎

👍

URI는 자원을 표현해야 하므로, show와 같은 행위가 포함되면 안된다. show는 HTTP Method인 GET을 통해 충분히 표현 가능하다.
자원은 <code>Collection</code>과 <code>Element</code>로 나누어 표현할 수 있고, 아래 테이블에 기초하여 서버 대부분과의 통신 행태를 표현할 수 있다.
<img src="https://s3-us-west-2.amazonaws.com/secure.notion-static.com/01735ab8-cec7-4208-a3eb-78e69fd87ed5/%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA_2021-08-31_%E1%84%8B%E1%85%A9%E1%84%8C%E1%85%A5%E1%86%AB_8.47.26.png" alt="사진">
<h3 id="patch-vs-put"><a href="#patch-vs-put" aria-label="patch vs put permalink"></a>PATCH vs PUT</h3>
<code>PUT</code>은 해당 자원의 전체를 교체한다는 의미 
<code>PATCH</code>는 일부를 변경한다는 의미
→ <code>update</code> 이벤트에서 PUT보다 의미적으로 더 적합하다는 평가
<h3 id="마지막에-code-classlanguage-textcode-를-포함하지-않는다"><a href="#%EB%A7%88%EC%A7%80%EB%A7%89%EC%97%90-code-classlanguage-textcode-%EB%A5%BC-%ED%8F%AC%ED%95%A8%ED%95%98%EC%A7%80-%EC%95%8A%EB%8A%94%EB%8B%A4" aria-label="마지막에 code classlanguage textcode 를 포함하지 않는다 permalink"></a>마지막에 <code>/</code> 를 포함하지 않는다.</h3>
👎

👍

<h3 id="_underbar-대신--dash-를-사용한다"><a href="#_underbar-%EB%8C%80%EC%8B%A0--dash-%EB%A5%BC-%EC%82%AC%EC%9A%A9%ED%95%9C%EB%8B%A4" aria-label="_underbar 대신 dash 를 사용한다 permalink"></a>_(underbar) 대신 -(dash) 를 사용한다.</h3>
👎
<div data-language="bash"><pre><code>POST /users/post_comments</code></pre></div>
👍
<div data-language="bash"><pre><code>POST /users/post-comments</code></pre></div>
<h3 id="소문자를-사용한다"><a href="#%EC%86%8C%EB%AC%B8%EC%9E%90%EB%A5%BC-%EC%82%AC%EC%9A%A9%ED%95%9C%EB%8B%A4" aria-label="소문자를 사용한다 permalink"></a>소문자를 사용한다</h3>
👎

👍
<div data-language="bash"><pre><code>POST /users/post-comments</code></pre></div>
<h3 id="컨트롤-자원을-의미하는-uri-예외적으로-동사를-허용한다"><a href="#%EC%BB%A8%ED%8A%B8%EB%A1%A4-%EC%9E%90%EC%9B%90%EC%9D%84-%EC%9D%98%EB%AF%B8%ED%95%98%EB%8A%94-uri-%EC%98%88%EC%99%B8%EC%A0%81%EC%9C%BC%EB%A1%9C-%EB%8F%99%EC%82%AC%EB%A5%BC-%ED%97%88%EC%9A%A9%ED%95%9C%EB%8B%A4" aria-label="컨트롤 자원을 의미하는 uri 예외적으로 동사를 허용한다 permalink"></a>컨트롤 자원을 의미하는 URI 예외적으로 동사를 허용한다.</h3>
함수처럼, 컨트롤 자원을 나타내는 URL은 동작을 포함하여 명명한다.
👎

👍

<h2 id="http-status"><a href="#http-status" aria-label="http status permalink"></a>HTTP Status</h2>
<h3 id="성공-응답은-code-classlanguage-text2xxcode-로-응답한다"><a href="#%EC%84%B1%EA%B3%B5-%EC%9D%91%EB%8B%B5%EC%9D%80-code-classlanguage-text2xxcode-%EB%A1%9C-%EC%9D%91%EB%8B%B5%ED%95%9C%EB%8B%A4" aria-label="성공 응답은 code classlanguage text2xxcode 로 응답한다 permalink"></a>성공 응답은 <code>2XX</code> 로 응답한다</h3>
<ul>
<li>200 : OK</li>
<li>
201 : CREATED
<ul>
<li>
200과 달리 요청에 성공하고, 새로운 리소스를 만든 경우에 응답
<ul>
<li>POST, PUT</li>
</ul>
</li>
</ul>
</li>
<li>
202 : ACCEPTED
<ul>
<li>
클라이언트 요청을 받은 후, 요청은 유효하지만 서버가 아직 처리하지 않은 경우
<ul>
<li>비동기 작업</li>
<li>요청에 대한 응답이 일정 시간 후 완료되는 작업인 경우</li>
<li>작업 완료 후 클라이언트에 알릴 수 있는 server push 작업을 하거나, 클라이언트가 해당 작업의 진행 상황을 조회할 수 있는 URI 응답해야함</li>
</ul>
<div data-language="json"><pre><code>HTTP/1.1 202 Accepted
{
			"links": [
				{
					"rel": "self",
					"method": "GET",
					"href": "https://api.test.com/v1/users/3"
				}
		]
}</code></pre></div>
</li>
</ul>
</li>
<li>
204 : NO Content
<ul>
<li>응답 body가 필요없는 자원 삭제 요청(DELETE) 같은 경우</li>
<li>200 응답 후 null, {}, [], false를 return 하는 것과 다르다. 아예 HTTP Body가 없음</li>
</ul>
</li>
</ul>
<h3 id="실패-응답은-code-classlanguage-text4xxcode로-응답한다"><a href="#%EC%8B%A4%ED%8C%A8-%EC%9D%91%EB%8B%B5%EC%9D%80-code-classlanguage-text4xxcode%EB%A1%9C-%EC%9D%91%EB%8B%B5%ED%95%9C%EB%8B%A4" aria-label="실패 응답은 code classlanguage text4xxcode로 응답한다 permalink"></a>실패 응답은 <code>4XX</code>로 응답한다</h3>
<ul>
<li>
400 : [Bad Request]
<ul>
<li>클라이언트 요청이 미리 정의된 파라미터 요구사항을 위반한 경우</li>
<li>
파라미터의 위치(<code>path</code>,&nbsp;<code>query</code>,&nbsp;<code>body</code>), 사용자 입력 값, 에러 이유 등을&nbsp;반드시&nbsp;알린다
<ul>
<li>case 1</li>
</ul>
<div data-language="json"><pre><code>{

 "message" : "'name'(body) must be Number, input 'name': test123"
}</code></pre></div>
<ul>
<li>case 2</li>
</ul>
<div data-language="json"><pre><code>{

 "errors": [

 {

 "location": "body",

 "param": "name",

 "value": "test123",

 "msg": "must be Number"
 }

 ]

}</code></pre></div>
</li>
</ul>
</li>
<li>401 : [Unauthorized]</li>
<li>
403 : [Forbidden]
<ul>
<li>해당 요청은 유효하나 서버 작업 중 접근이 허용되지 않은 자원을 조회하려는 경우</li>
<li>접근 권한이 전체가 아닌 일부만 허용되어 요청자의 접근이 불가한 자원에 접근 시도한 경우 응답한다.</li>
</ul>
</li>
<li>404 : [Not Found]</li>
<li>
405 : [Method Not Allowed]
<ul>
<li>405 code는 404 code와 혼동될 수 있기 때문에 룰을 잘 정하고 시작한다.</li>
<li>
<code>POST /users/1</code>의 경우 404로 응답한다고 생각할 수 있지만, 경우에 따라&nbsp;405로 응답할 수 있다.&nbsp;<code>/users/:id</code>&nbsp;URL은 GET, PATCH, DELETE method는 허용되고 POST는 불가한 URL이다.
<ul>
<li>만약 id가&nbsp;<code>1</code>인 사용자가 없는 경우엔 404로 응답하지만(GET, PATCH, DELETE의 경우),&nbsp;<code>POST /users/1</code>는&nbsp;<code>/users/:id</code>&nbsp;URL이 POST method를 제공하지 않기 때문에 405로 응답하는 게 옳다.</li>
</ul>
</li>
<li><code>Allow: GET, PATCH, DELETE</code>&nbsp;HTTP header에 허용 가능한 method를 표시한다.</li>
</ul>
</li>
<li>
409 : [Conflict]
<ul>
<li>해당 요청의 처리가 비지니스 로직상 불가능하거나 모순이 생긴 경우</li>
<li>
e.g.)&nbsp;<code>DELETE /users/hak</code>의 경우, 비지니스 로직상 사용자의 모든 자원이 비어있을 때만 사용자를 삭제할 수 있는 규칙이 있을 때 409로 응답한다.
<div data-language="json"><pre><code>409 Conflict

{

 "message" : "first, delete connected resources."
 "links": [

 {

 "rel": "posts.delete",

 "method": "DELETE",

 "href": "https://api.test.com/v1/users/hak/posts"
 },

 {

 "rel": "comments.delete",

 "method": "DELETE",

 "href": "https://api.test.com/v1/users/hak/comments"
 }

 ]

}</code></pre></div>
</li>
</ul>
</li>
<li>
429 : [Too Many Requests]
<ul>
<li><code>Retry-After: 3600</code>(HTTP Headers)</li>
<li>DoS, Brute-force attack 같은 비정상적인 접근을 막기 위해 요청의 수를 제한한다.</li>
</ul>
</li>
</ul>
<h2 id="입력-form-형태"><a href="#%EC%9E%85%EB%A0%A5-form-%ED%98%95%ED%83%9C" aria-label="입력 form 형태 permalink"></a>입력 Form 형태</h2>
새로운 Item 작성하거나 기존의 Item을 수정하는 경우, 작성/수정 Form은 어떻게 제공해야 할까?
→ Form 자체로도 정보로 취급
<img src="https://s3-us-west-2.amazonaws.com/secure.notion-static.com/32c01163-68ad-4d7c-a9dc-64620143fe22/%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA_2021-08-31_%E1%84%8B%E1%85%A9%E1%84%8C%E1%85%A5%E1%86%AB_8.50.28.png" alt="스크린샷 2021-08-31 오전 8.50.28.png">
<h2 id="모바일-환경에-따라-다른-정보를-보여야-하는-경우"><a href="#%EB%AA%A8%EB%B0%94%EC%9D%BC-%ED%99%98%EA%B2%BD%EC%97%90-%EB%94%B0%EB%9D%BC-%EB%8B%A4%EB%A5%B8-%EC%A0%95%EB%B3%B4%EB%A5%BC-%EB%B3%B4%EC%97%AC%EC%95%BC-%ED%95%98%EB%8A%94-%EA%B2%BD%EC%9A%B0" aria-label="모바일 환경에 따라 다른 정보를 보여야 하는 경우 permalink"></a>모바일 환경에 따라 다른 정보를 보여야 하는 경우</h2>
REST API는 URI가 플랫폼 중립적이어야 하기 때문에, Request Header의 <code>User-Agent</code> 값을 참조하는 것이 좋다.
아이폰에서의 User-Agent&gt;
<div data-language="java"><pre><code>Mozilla/5.0 (iPhone; U; CPU like Mac OS X; en) AppleWebKit/420+ (KHTML, like Gecko) Version/3.0 Mobile/1A543a Safari/419.3</code></pre></div>
출처 
<a href="https://sanghaklee.tistory.com/57">https://sanghaklee.tistory.com/57</a>
<a href="https://spoqa.github.io/2012/02/27/rest-introduction.html">https://spoqa.github.io/2012/02/27/rest-introduction.html</a></div></div>

Seulog💘

이예슬

📌 설계 중심 규칙
URI는 정보의 자원을 표현해야 한다
자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)으로 표현한다
URI 작성 규칙
👎
GET /users/show/1
👍
GET /users/1
URI는 자원을 표현해야 하므로, show와 같은 행위가 포함되면 안된다. show는 HTTP Method인 GET을 통해 충분히 표현 가능하다.
자원은 Collection과 Element로 나누어 표현할 수 있고, 아래 테이블에 기초하여 서버 대부분과의 통신 행태를 표현할 수 있다.
PATCH vs PUT
PUT은 해당 자원의 전체를 교체한다는 의미 
PATCH는 일부를 변경한다는 의미
→ update 이벤트에서 PUT보다 의미적으로 더 적합하다는 평가
마지막에 / 를 포함하지 않는다.
👎
GET /users/1/
👍
GET /users/1
_(underbar) 대신 -(dash) 를 사용한다.
👎
POST /users/post_comments
👍
POST /users/post-comments
소문자를 사용한다
👎
POST /users/postComments
👍
POST /users/post-comments
컨트롤 자원을 의미하는 URI 예외적으로 동사를 허용한다.
함수처럼, 컨트롤 자원을 나타내는 URL은 동작을 포함하여 명명한다.
👎
POST /posts/duplicating
👍
POST /posts/duplicate
HTTP Status
성공 응답은 2XX 로 응답한다
200 : OK
201 : CREATED
200과 달리 요청에 성공하고, 새로운 리소스를 만든 경우에 응답
POST, PUT
202 : ACCEPTED
클라이언트 요청을 받은 후, 요청은 유효하지만 서버가 아직 처리하지 않은 경우
비동기 작업
요청에 대한 응답이 일정 시간 후 완료되는 작업인 경우
작업 완료 후 클라이언트에 알릴 수 있는 server push 작업을 하거나, 클라이언트가 해당 작업의 진행 상황을 조회할 수 있는 URI 응답해야함
HTTP/1.1 202 Accepted
{
			"links": [
				{
					"rel": "self",
					"method": "GET",
					"href": "https://api.test.com/v1/users/3"
				}
		]
}
204 : NO Content
응답 body가 필요없는 자원 삭제 요청(DELETE) 같은 경우
200 응답 후 null, {}, [], false를 return 하는 것과 다르다. 아예 HTTP Body가 없음
실패 응답은 4XX로 응답한다
400 : [Bad Request]
클라이언트 요청이 미리 정의된 파라미터 요구사항을 위반한 경우
파라미터의 위치(path, query, body), 사용자 입력 값, 에러 이유 등을 반드시 알린다
case 1
{
    "message" : "'name'(body) must be Number, input 'name': test123"
}
case 2
{
    "errors": [
        {
            "location": "body",
            "param": "name",
            "value": "test123",
            "msg": "must be Number"
        }
    ]
}
401 : [Unauthorized]
403 : [Forbidden]
해당 요청은 유효하나 서버 작업 중 접근이 허용되지 않은 자원을 조회하려는 경우
접근 권한이 전체가 아닌 일부만 허용되어 요청자의 접근이 불가한 자원에 접근 시도한 경우 응답한다.
404 : [Not Found]
405 : [Method Not Allowed]
405 code는 404 code와 혼동될 수 있기 때문에 룰을 잘 정하고 시작한다.
POST /users/1의 경우 404로 응답한다고 생각할 수 있지만, 경우에 따라 405로 응답할 수 있다. /users/:id URL은 GET, PATCH, DELETE method는 허용되고 POST는 불가한 URL이다.
만약 id가 1인 사용자가 없는 경우엔 404로 응답하지만(GET, PATCH, DELETE의 경우), POST /users/1는 /users/:id URL이 POST method를 제공하지 않기 때문에 405로 응답하는 게 옳다.
Allow: GET, PATCH, DELETE HTTP header에 허용 가능한 method를 표시한다.
409 : [Conflict]
해당 요청의 처리가 비지니스 로직상 불가능하거나 모순이 생긴 경우
e.g.) DELETE /users/hak의 경우, 비지니스 로직상 사용자의 모든 자원이 비어있을 때만 사용자를 삭제할 수 있는 규칙이 있을 때 409로 응답한다.
409 Conflict
{
    "message" : "first, delete connected resources."
    "links": [
        {
            "rel": "posts.delete",
            "method": "DELETE",
            "href":  "https://api.test.com/v1/users/hak/posts"
        },
        {
            "rel": "comments.delete",
            "method": "DELETE",
            "href":  "https://api.test.com/v1/users/hak/comments"
        }
    ]
}
429 : [Too Many Requests]
Retry-After: 3600(HTTP Headers)
DoS, Brute-force attack 같은 비정상적인 접근을 막기 위해 요청의 수를 제한한다.
입력 Form 형태
새로운 Item 작성하거나 기존의 Item을 수정하는 경우, 작성/수정 Form은 어떻게 제공해야 할까?
→ Form 자체로도 정보로 취급
모바일 환경에 따라 다른 정보를 보여야 하는 경우
REST API는 URI가 플랫폼 중립적이어야 하기 때문에, Request Header의 User-Agent 값을 참조하는 것이 좋다.
아이폰에서의 User-Agent>
Mozilla/5.0 (iPhone; U; CPU like Mac OS X; en) AppleWebKit/420+ (KHTML, like Gecko) Version/3.0 Mobile/1A543a Safari/419.3
출처 
https://sanghaklee.tistory.com/57
https://spoqa.github.io/2012/02/27/rest-introduction.html

RESTFul API 설계 가이드 정리

댓글