[ Rest API ] REST API 특징

---

REST API 특징

---

 

리소스 중심적

 

API 는 리소스를 중심으로 구성 되어야 한다. 이전에 언급 했듯이 리소스는 서비스가 리소스를 클라이언트에게 제공할 수 있게 정보를 추상화 한 것이다.

리소스의 내부 구조는 API 를 통해 유출되지 않아야 한다.

예를 들어 주문의 세부 사항은 관계형 데이터 베이스네 개별적으로 저장 될 수 있으므로 해당 내부 구조를 반영하도록 여러 리소스를 생성해서는 안된다.

API 는 비지니스 실체에 초점을 맞춰 구현 세부 사항을 숨기기 위한 추상화로써 리소스를 사용해 API 구현을 진화 시킬 수 있어야 한다.

 

---

 

URL 을 통한 식별 가능

 

리소스는  URL 을 통해 식별 할 수 있어야 한다.

이는 동사 대신 명사를 기반으로 한다.

리소스의 컬렉션을 식별하는 해당 URL 은 복수형이어야 한다.

• 주문 컬렉션
  • https://api.examplebucks.ork/v1/order
• ID 가 1234 일 때의 주문
  • https://api.examplebucks.ork/v1/order/1234
• 사용자 컬렉션
  • https://api.examplebucks.ork/v1/user
• ID 가 5678 인 사용자
  • https://api.examplebucks.ork/v1/user/5678

 

---

 

HTTP 메소드를 통한 작업 정의

 

리소스에서 수행할 수 있는 작업은 HTTP 메소드를 통해 정의해야 한다.

다음은 RESTful API 에서 사용되는 일반적인 메소드이다.

 

GET

 

GET 메소드는 지정된 URL 에서 리소스의 표현을 검색한다.

API 의 응답에는 요청된 리소스의 세부 사항을 포함한다.

이 메소드는 안전한 작업으로 구현 되어야 한다.

 

즉, 리소스에 대한 GET 작업을 수행하는 것은 어떤 상태에도 영향을 끼쳐서는 안된다는 것을 의미한다.

그것은 여러번 호출할 수 있고 이 작업에 대한 응답은 캐싱할 수 있다.

 

POST

 

POST 메소드는 지정된 URL 에 새로운 리소스를 생성한다.

리소스의 식별자는 서버에 의해 생성된다.

API 의 응답에는 새로운 리소스에 대한 세부 사항이 포함된다.

 

POST 메소드는 불안정한 작업이다.

즉, 장단점이 있다.

POST 요청을 여러 번 시도하면 서버 측면에서 다른 리소스를 생성할 것이다.

 

POST 요청을 여러번 시도하면 서버 측면에서 다른 리소스를 생성할 것이다.

 

또한 POST 요청은 예를 들어 TaskAgile  애플리케이션에서 카드를 이동하는 것처럼

새로운 리소스를 생성하는 것 말고도 다른 작업을 수행하는 데 활용할 수 있다.

 

PUT

 

PUT 메소드는 새로운 리소스를 생성하거나 기존 리소스를 업데이트 한다.

클라이언트는 리소스에 대한 URL 을 지정하고 요청 본문에는 리소스의 완전한 표현을 포함한다.

지정된 URL 과 리소스가 이미 존재 한다면 대체될 것이다.

그렇지 않으면 새로운 리소스가 생성이 될 것이다.

 

새로운 리소스가 생성될 때 PUT 과 POST 를 사용하는 것의 차별자를 선택하는 것을 허용하지 않는다면

PUT 메소드는 기존 리소스를 업데이트 할 때만 사용해야 한다.

 

그리고 지정된 URL 에 리소스가 존재하지 않는다면 클라이언트로 HTTP 404 응답이 반환될 것이다.

PUT 메소드는 같은 효과가 여러번 수행될 수 있는 방식으로 구현되어야 한다.

이것은 PUT 메소드가 멱등성이 있음을 의미한다.

 

PATCH

 

PATCH 메소드는 기존 리소스의 일부를 업데이트 한다.

클라이언트가 리소스의 URL 을 지정해 요청 본문에 리소스 표현의 일부분만 포함된다.

 

PATCH 메소드와 PUT 메소드의 차이점은

보통 PUT 메소드의 요청 본문에는 리소스의 완전한 표현을 포함하고

PATCH 메소드는 표현의 일부분만 포함된다는 점이다.

 

또 다른 차이점은 PATCH 메소드는 불안전하고 멱등성도 아니다.

 

DELETE

 

DELETE 메소드는 지정된 URL 에서 기존의 리소스를 제거한다.

DELETE 메소드는 멱등성을 띈다.

즉, 같은 리소스에 DELETE 메소드를 여러번 수행하면 해당 리소스의 상태는 항상 같음 ( 활용할 수 없음 ) 을 나타낸다.

 

 

---

 

HTTP 상태 코드 사용

 

RESTful API 는 요청에 대한 결과를 나타내고자 HTTP 표준으로 정의된 의미 있는 상태 코드를 사용한다.

 

 

2 XX - 성공 코드

 

• 200 OK 
  • GET 이나 PUT, PATCH 요청이 성공 했음을 나타낸다.
  • 또한 리소스 생성을 위한 것이 아닌 POST 요청이나 응답에 제거된 리소스의 표현이 포함될 필요가 있을 때 DELETE 요청에 활용될 수 있다.
• 201 작성 (Created)
  • 새로운 리소스를 생성하기 위한 POST 요청 또는 PUT 요청이 성공했음을 나타낸다.
  • 일반적으로 location 헤더는 새로운 리소스의 url 와 함께 반환 된다.
• 204 내용 없음 (No Content)
  • DELETE 요청과 같은 응답 본문을 포함하지 않는 성공적인 요청을 나타낸다.

 

 

3 XX - 리 다이렉션

 

• 304 수정되지 않음 (Not Modified)
  • 마지막 요청 이후 리소스가 수정되지 않았음을 나타낸다.
  • 일반적으로 클라이언트는 if-Modified-Since 같은 헤더를 제공해 비교할 시간을 제공한다.

 

 

4 XX - 클라이언트 에러

 

• 404 잘못된 요청 (Bed Request)
  • 클라이언트 에러로 인식되는 어떤 것으로 인해 서버가 해당 요청을 처리할 수 없거나 처리하지 못함을 뜻한다. 예를 들어 요청이 잘못된 형식이거나 유효성 검사에 실패한 것이다.
• 401 권한 없음 (Unauthorized)
  • 인증 자격 증명을 포함하지 않거나 인증에 실패한 요청을 나타난다.
• 403 금지됨 (Forbidden)
  • 인증된 사용자에게 허용되지 않은 리소스에 접근을 시도하는 요청을 나타낸다.
• 404 찾을 수 없음 (Not Found)
  • 존재하지 않는 리소스에 대한 요청을 나타낸다.
• 409 충돌 (Conflixt)
  • 리소스의 상태가 충돌했기 떄문에 리소스의 상태를 변경하려는 시도가 서버에 의해 처리 될 수 없음을 나타낸다.
• 410 사라짐 (Gone)
  • 요청된 리소스가 더 이상 이용할 수 없음을 나타낸다.
• 429 너무 많은 요청 (Too Many Requests)
  • 클라이언트가 주어진 시간 동안 너무 많은 요청을 보냈고 거부됐음을 나타낸다.
  • 서버는 응답에 Retry-After 헤더를 포함할 수 있다.
  • 이는 새로운 요청을 생성하기 이전에 얼마나 오래 대기해야 하는지를 나타낸다,

 

5 XX - 서버 에러

 

• 500 내부 서버 에러 (Internet Server Error)
  • 서버가 예기치 않은 조건을 발견해 요청을 처리하지 못했음을 나타낸다.

 

---