코드스테이츠 소프트웨어엔지지어링 부트캠프 +47일,

• 5가지의 기본적인 REST API 디자인 가이드

공부도 할 겸, 앞으로 영어문서를 많이 읽게 될텐데 연습도 할겸, 해석을 해보았다.

5 Basic REST API Design Guidelines

 

1. Resource(URIs)

리소스를 표시하려면 동사가 아닌 구체적인 명사를 사용해야한다.
과거에 개발자들은 RPC방식으로 서비스의 의미를 전달하기 위해 동사를 사용했다.
ex) getUser(1234), createUser(user), deleteAddress(1234) 등

하지만 RESTful 접근방식은 다음과 같다.
GET /users/1234 POST /users (with JSON describing a user in the body) DELETE /addresses/1234

2. HTTP methods

REST접근의 목적중 하나는 HTTP를 프로토콜 어플리케이션으로 이용하는 것이다.
그러므로 우리는 리소스에 HTTP동사들을 사용해서 리소스에 어떤 액션들이 취해지는지 표시해야 하고 개발자들의 반복적인 CRUD작업을 용이하게 해야한다.

밑에 소개하는 메소드들은 자주 이용되는 메소드들이다.

• GET : GET메소드는 주어진 URI를 사용하여 서버로부터 정보를 조회하기 위해 사용된다. GET을 사용하는 request는 데이터를 조회하기만 할 뿐 데이터에 어떤 영향도 미치지 않는다.
• HEAD : GET메소드와 비슷하지만 status line과 header 섹션만 전송한다.
• POST : POST request는 서버로 데이터를 보낼 때 사용된다. ex) customer imformation, file upload
• PUT : 현재 모든 자료들을 업로드된 컨텐츠로 바꾼다. 전체 업데이트
• PATCH : 부분 업데이트한다.
• OPTIONS : ~ 해도 되겠니? 라고 사전에 물어보는 역할
• DELETE : 삭제
• PUT과 PATCH의 차이 : PUT은 해당 위치에 있는 리소스의 모든 컨텐츠를 바꾸는 반면, PATCH는 부분만 변화를 준다.

3. HTTP Headers

HTTP Header는 4가지 종류가 있다.

• General Header : request,response 메시지에 적용할 수 있다.
• Client Request Header : request 메시지들에만 적용할 수 있다.
• Sever Response Header : response 메시지들에만 적용할 수 있다.
• Entity Header : Entity본문에 대한 메타정보를 정의한다. Body가 없을 땐, request에 의해 정의된 리소스들만 정의한다. 

4. Query Parameters

• Paging : API 디자인 초기단계에 리소스의 페이지를 예측할 수 있어야 한다. 리턴될 데이터의 양을 정확하게 예측하는 건 어렵다.
  그러므로, 호출 클라이언트에서 제공하지 않는 경우(예 : 값범위 (0~25)), 리소스에 초기값을 페이지화하는걸 추천한다.
• Filtering : 필터링은 일부 속성이나 예상 값을 지정하여 조회되는 리소스의 수를 제한한다. 여러 속성의 컬렉션을 동시에 필터링 하고 하나의 필터링된 속성에 대해 여러 값들을 허용하는게 가능하다.
• Sorting : 리소스의 컬렉션을 조회한 결과를 정렬한다. 정렬 매개변수는 정렬이 수행되는 속성의 이름을 쉼표로 구분하여 포함한다.
• Searching : 검색은 컬랙션의 하위 리소스이다. Searching의 결과는 리소스 및 컬렉션 자체와는 다른 형식을 갖는다. 이를 통해 검색과 관련된 제안, 수정 및 정보를 추가할 수 있다. 매개변수는 쿼리 문자열을 통해 필터와 동일한 방식으로 제공된다.(permit approximate matching-> 조금은 달라도 된단 뜻?인가??)

5. Status Codes

• 200 - OK : 모든게 다 잘 돌아간다.
• 201 - Created : 새로운 리소스가 생성되었다.
• 204 - No Content : 리소스가 성공적으로 삭제되었다. 응답본문이 없음(No response body)
• 304 - Not Modified : 이것은 캐시를 목적으로 사용된다. 이것은 클라이언트에게 응답이 수정되지 않았음을 알려주며, 그러므로 클라이언트는 계속해서 응답의 캐시된 버전을 사용할 수 있다.
• 400 - Bad Request : request가 유효하지 않음
• 401 - Unathorized : response를 받기 위해 인증이 필요하다.
• 403 - Forbidden : 서버에 요청이 받아들여졌지만 거부당하거나 접근이 허용되지 않음
• 404 - Not found : 서버가 요청받은 리소스를 찾을 수 없다. 브라우저에서는 알려지지 않은 URL을 의미한다. 이것은 API에서 종점은 적절하지만 리소스 자체는 존재하지 않음을 의미한다. 
• 500 - Internal Server Error : API 개발자들은 이 에러를 피해야 한다. 에러가 global catch blog에서 발생하면 스택 추적이 기록되고 response로 반환되지 않아야 함.