REST API의 규칙

ggyu_55·2023년 4월 16일

메모

목록 보기

18/46

URI는 자원을 표현하는 데에 집중하고 행위에 대한 정의는 HTTP METHOD를 통해 해야 한다.
```
 DELETE /members/1 
```
와 같이 자원에 대한 행위(HTTP 메소드)와 대상이 되는 자원을 명시하는게 좋다.
```
   GET /members/delete/1
```
와 같이 리소스명에 동사를 쓰는 것은 바람직하지 못하다.

HTTP 메서드의 알맞은 역할

POST :: POST를 통해 해당 URI을 요청하면 리소스를 생성한다.

GET :: GET을 통해 해당 리소스를 조회한다. 리소스를 조회하고 해당 문서에 대한 자세한 정보를 가져온다.

PUT :: PUT을 통해 해당 리소스를 수정한다.

DELETE :: DELETE를 통해 리소스를 삭제한다.

    http://restapi.example.com/houses/apartments
    http://restapi.example.com/animals/mammals/whales

URI 마지막 문자로 슬래시(/)를 포함하지 않는다.

URI가 다르다는 것은 리소스도 다르다는 뜻!! URI는 리소스를 구별하는 유일한 식별자로 사용되어야 한다. 서로 다른 URI가 같은 리소스를 가리켜서는 안된다.

    http://restapi.example.com/houses/apartments/ (X)
    http://restapi.example.com/houses/apartments  (0)

하이픈(-)은 URI 가독성을 높이는데 사용
밑줄보다 눈에 잘 띄고 구별이 잘 된다.
밑줄(_)은 URI에 사용하지 않는다.
마찬가지로 가독성 문제가 있을 수 있음. 잘 보이지 않을 수 있다.
URI 경로에는 소문자가 적합하다
RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정한다. 따라서 대소문자에 따라 다른 URI로 인식하므로 소문자만 사용하는 것이 편리하다.
파일 확장자는 URI에 포함시키지 않는다.
REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다. Accept header를 사용하자
```
http://restapi.example.com/members/soccer/345/photo.jpg (X)
GET / members/soccer/345/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg (O)
```

REST 리소스 간에는 연관 관계가 있을 수 있고, 이런 경우 다음과 같은 표현방법으로 사용한다.

    /리소스명/리소스 ID/관계가 있는 다른 리소스명

    ex)    GET : /users/{userid}/devices (일반적으로 소유 ‘has’의 관계를 표현할 때)

관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현한다.

    GET : /users/{userid}/likes/devices (관계명이 애매하거나 구체적 표현이 필요할 때)

Document :: 문서? 객체!

Collection  :: Document의 집합

도큐먼트와 콜렉션 둘 모두 리소스라고 표현할 수 있고 URI에 표현된다.

   http:// restapi.example.com/sports/soccor/players/13

{sports, players} Collection과 {soccor,13} Document로 URI가 이루어진다. 컬렉션은 복수로 사용하는 점에 주의하면 편하게 구별할 수 있다.

200 :: 클라이언트의 요청을 정상적으로 수행함

201 :: 클라이언트가 어떠한 리소스 생성을 요청, 해당 리소스가 성공적으로 생성됨(POST를 통한 리소스 생성 작업 시)

400 :: 클라이언트의 요청이 부적절 할 경우 사용하는 응답 코드

401 :: 클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 때 사용하는 응답 코드
(로그인 하지 않은 유저가 로그인 했을 때, 요청 가능한 리소스를 요청했을 때)

403 :: 유저 인증상태와 관계 없이 응답하고 싶지 않은 리소스를 클라이언트가 요청했을 때 사용하는 응답 코드
(403 보다는 400이나 404를 사용할 것을 권고. 403 자체가 리소스가 존재한다는 뜻)

404 :: 서버에 없는 리소스를 클라이언트가 요청했을 때 사용하는 응답코드

405 :: 클라이언트가 요청한 리소스에서는 사용 불가능한 Method를 이용했을 경우 사용하는 응답 코드

301 :: 클라이언트가 요청한 리소스에 대한 URI가 변경 되었을 때 사용하는 응답 코드
(응답 시 Location header에 변경된 URI를 적어야 한다.)

500 :: 서버에 문제가 있을 경우 사용하는 응답 코드

참고 : https://meetup.nhncloud.com/posts/92