REST API 가이드

1. REST API 설계시 가장 중요한 다섯가지 규칙

 

✅ URI는 정보의 자원을 표현

✅ ****자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현

 

 

1. 소문자를 사용한다.

주소에서 대소문자를 구분하므로, 카멜방식이 아닌 소문자를 사용하여 작성한다.

Bad

http://ssafe.com/users/postComments

Good

http://ssafe.com/users/post-comments

 

 

2. 언더바를 대신 하이픈을 사용한다.

가급적 하이픈의 사용도 최소화하며, 정확한 의미나 표현을 위해 단어의 결합이 불가피한 경우에 사용한다.

Bad

http://ssafe.com/users/post_comments

Good

http://ssafe.com/users/post-comments

 

 

3. 마지막에 슬래시를 포함하지 않는다.

슬래시는 계층을 구분하는 것으로, 마지막에는 사용하지 않는다.

Bad

http://ssafe.com/users/

Good

```
http://ssafe.com/users
```

 

 

4. 행위는 포함하지 않는다.

행위는 URL대신 Method를 사용하여 전달한다.(GET, POST, PUT, DELETE 등)

Bad

POST http://ssafe.com/users/1/create-posts
DELETE http://ssafe.com/users/1/delete-post/1
PUT http://ssafe.com/users/1/update-post/1

Good

POST http://ssafe.com/users/1/posts
DELETE http://ssafe.com/users/1/posts/1
PUT http://ssafe.com/users/1/posts/1

 

 

5.파일 확장자는 URI에 포함시키지 않는다.

REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 말고 Accept header를 사용하도록 한다.

Bad

http://ssafe.com/users/moram.jpg

Good

GET http://ssafe.com/users/moram

HTTP/1.1 Host: ssafe.com Accept: image/jpg

 

 

6. 가급적 전달하고자하는 자원의 명사를 사용하되, 컨트롤 자원을 의미하는 경우 예외적으로 동사를 허용한다.

Bad

http://ssafe.com/posts/registering

Good

http://ssafe.com/posts/register

2. HTTP Status Code 정리

 

🚩 HTTP 응답 코드

✅ 200번대 : 성공

• 200: Ok, 클라이언트의 요청을 정상적으로 수행함.
• 201: Created, 클라이언트에게 생성 작업을 요청받았고, 생성 작업을 성공함.
• 204: No Content, 요청은 성공했으나 응답할 콘텐츠가 없음.
• 205: Reset Content, 요청은 성공했으나 클라이언트의 화면을 새로 고침하도록 권고
• 206: Partial Content, 요청은 성공했으나 일부 범위의 데이터만 반환함.

✅ 300번대 : 리다이렉션

• 301: Moved Permantly, 클라이언트가 요청한 리소스에 대한 URI가 영구적으로 변경되었음을 의미.
• 302: Found, 요청한 URI가 일시적으로 주소가 바뀌었을 경우를 의미.
• 303: See Other, 요청한 자원이 임시 주소에 존재함.
• 304: Not Modified, 이전에 방문했을 때의 요청 결과와 다르지 않을 경우(캐시 된 페이지를 그대로 사용)
• 307: Temporary Redirect, 임시 페이지로 리다이렉트.

✅400번대 : 클라이언트 오류

• 400: Bad Request, 클라이언트가 올바르지 못한 요청을 보냄.
• 401: Unauthorized, 인증 혹은 승인되지 않은 접근(로그인을 하지 않아 페이지를 열 권한이 없음)
• 403: Forbidden, 금지된 페이지, 로그인을 하든 안하든 접근할 수 없음. (관리자 페이지)
• 404: Not found, 찾을 수 없는 페이지, 주소를 잘 못 입력했을 때 사용함.인증받지 않은 클라이언트로 부터 리소스를 숨기기 위해 403 대신에 사용할 수도 있음.(해커들의 공격을 방지하고자 페이지가 없는 것처럼 위장하는 경우)
• 405: Method Not Allowed, 허용되지 않은 요청 메소드를 받았을 경우.
• 408: Request Timeout, 요청 시간이 초과됨.
• 409: Conflict, 서버가 요청을 처리하는 과정에서 충돌이 발생한 경우. (회원가입 중 중복된 아이디인 경우)
• 410: Gone, 영구적으로 사용할 수 없는 페이지.

✅500번대 : 서버 오류

• 501: Not Implemented, 해당 요청을 처리하는 기능이 만들어지지 않음.
• 502: Bad Gateway, 서버로 가능 요청이 중간에서 유실된 경우.
• 503: Service Unavailable, 서버가 터졌거나 유지 보수 중(유지 보수 중일때는 유지 보수 중이라는 것을 알려주는 페이지로 전송해주는 것이 좋음)
• 504: Gateway Timeout, 서버 게이트웨이에 문제가 생겨 시간 초과가 된 경우.
• 505: HTTP Version Not Surpported, HTTP 버전이 달라 요청이 처리할 수 없음.

---

참고 URL