[PROGRAMMING] RESTful API설계

REST

웹에 존재하는 모든 자원( DB, 이미지 등 )에 고유한 URL을 부여하여 활용하게 하는 아키텍처

자원마다 고유한 URL을 부여하여 자원의 활용이 이루어지기 때문에 각 URL의 설계가 이전보다 중요하게 되어 해당 URL만 보더라도 어떤 작업이 이루어지는지 알 수 있도록 설계해야 한다.

 

장점

하나의 환경에 집중되어 설계하는 것이 아닌 다양한 디바이스 환경 ( 안드로이드, ios, 웹 등 )에게 서비스를 제공하는 것이 가능하다는 장점이 있다.

 

메소드

메소드	규칙 설명
GET	데이터를 조회할 때 활용되는 메소드
POST	새로운 데이터를 Write할 때 활용되는 메소드
PUT	데이터를 수정할 때 활용되는 메소드
PATCH	데이터를 수정할 때 활용하는 메소드
DELETE	데이터를 삭제할 때 활용되는 메소드

 

Params / Header / Body

- Params

http://localhost:8080/artSharing/art/list?pageNo=1

흔하면서도 간단하게 URI 뒤에 Key/Value를 붙이는 개념

하지만 Key가 URL에 노출이 되기 때문에 보안에 취약

인증 용도로써는 부적합하고 정렬 혹은 검색이 필요할 때 사용하도록 권고됨.

 

- Header

Header은 Key와 Value로만 표현이 가능하고, 보통 인증 혹은 인증 후 권한 확인을 위해 사용됨.

 

- Body

API 통신을 통한 데이터 요청에 있어, 어떤 특정 데이터에 대한 응답을 받고자 할 때, 특정 정보를 요청할 때 사용됨.

보통은 Key, Value 표현에 있어선 JSON 형식으로 표현을 많이함

 

URI 명명 규칙

1. 언더바 표현 규칙

-(dash)의 사용도를 최소한으로 설계한다. 정확한 의미나 표현을 위해 단어의 결합이 불가피한 경우 반드시 _(underbar) 대신 -(dash)를 사용한다.

Bad

http://api.test.com/users/post_commnets

Good

http://api.test.com/users/post-commnets

 

2. 마지막에 /를 포함하지 않는다.

Bad

http://api.test.com/users/

Good

http://api.test.com/users

 

3. 소문자를 사용한다.

Bad

http://api.test.com/users/postComments

Good

http://api.test.com/users/post-comments

 

4. 행위 ( method ) 는 URL에 포함하지 않는다.

Bad

POST http://api.test.com/users/1/delete-post/1

Good

DELETE http://api.test.com/users/1/posts/1

 

5. 컨트롤 자원을 의미하는 URL에서는 예외적으로 동사를 허용한다.

함수처럼, 컨트롤 리소스를 나타내는 URL은 동작을 포함하는 이름을 짓는다.

Bad

http://api.test.com/posts/duplicating

Good

http://api.test.com/posts/duplicate

 

 

HTTP 헤더

1. Content-Location

 : POST 요청은 대부분 멱등(반환되는 응답 리소스의 결과가 항상 동일)하지 않다.

POST /users
{
	"name": "jaeho"
}

첫 번째는 /users/1, 두 번째는 /users/2 ... n번째는 /users/n 으로 반환이 된다.

따라서 요청의 응답 헤더에 새로 생성된 리소스를 식별할 수 있는 Content-Location 속성을 이용한다.

HTTP/1.1 200 OK
Content-Location: /users/1

 

GET, PUT 등의 요청은 멱등하다.

GET /users/1 의 경우 언제나 같은 결과로 응답한다.

PUT을 POST처럼 쓰는 경우엔 멱등하지 않을 수 있다.

 

2. Content-Type

Content-Type: application/json; charset-utf8

해당 개체에 포함되는 미디어 타입 정보

application/json을 우선으로 제공한다.

응답 포맷을 여러 개로 나누면 요청 포맷도 나눠야 한다.

 

HTTP 상태

1. 의미에 맞는 HTTP status를 리턴한다.

Bad

HTTP/1.1 200 OK
{
	"result" : false
	"status" : 400
}

위를 보면 상태는 200으로 성공인데 body 내용엔 실패에 관한 내용을 리턴하고 있다.

Good

HTTP/1.1 400 Bad Request
{
	"msg" : "check your parameter"
}

 

2. HTTP status 만으로 상태 에러를 나타낸다.

세부 에러 사항은 응답 객체에 표시하거나 해당 에러를 확인할 수 있는 링크를 표시한다.

Bad

HTTP/1.1 404 Not Found
{
	"code" : 404,
	"error_code": -765
}

Good

HTTP/1.1 404 Not Found
{
	"code" : -765,
	"more_info" : "https://api.test.com/errors/-765"
}

HTTP 상태 코드

1. 성공 응답은 2XX로 응답한다.

- 200 : [OK]

- 201 : [Created] (새로운 리소스를 만든 경우에 응답한다, POST나 PUT에 사용)

- 202 : [Accepted]

       클라이언트 요청을 받은 후, 요청은 유효하나 서버가 아직 처리하지 않은 경우에 응답한다. 비동기 작업

• 요청에 대한 응답이 일정 시간 후 완료되는 작업의 경우

• 작업 완료 후 클라이언트에 알릴 수 있는 server push 작업을 하거나, 클라이언트가 해당 작업의 진행 상황을 조회할 수 있는 URL을 응답해야 한다.

HTTP/1.1 202 Accepted
{
	"links": [
		{
			"rel": "self",
			"method": "GET",
			"href": "https://api.test.com/v1/users/3"
		}
	]
}

 

- 204 : [No Content]

• 응답 body가 필요 없는 자원 삭제 요청(DELETE) 같은 경우 응답한다.
• 200 응답 후 body에 null, {}. [], false로 응답하는 것과는 다름 ( 204는 body가 아예 없음 )

 

2. 실패 응답은 4XX로 응답한다.

- 400 : [Bad Request]

• 클라이언트 요청이 미리 정의된 파라미터 요구 사항을 위반한 경우
• 클라이언트의 요청이 부적절할 경우에 사용
• 파라미터 위치, 사용자 입력 값, 에러 이유 등을 반드시 알린다.

{
	"message" : "'name'(body) must be Number, input 'name': test123"
}

{
	"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] ( 해당 요청의 처리가 비즈니스 로직상 불가능하거나 모순이 생긴 경우 )

- 429 : [Too Many Requests] ( DoS, Brute-force attack 같은 비정상적인 접근을 막기 위해 요청의 수를 제한 )

 

3. 5XX 에러는 절대 사용자에게 나타내지마라

5XX 에러는 서비스 장애를 의미한다.

API Server는 모든 발생 가능한 에러를 핸들링해야 한다.

 

 

 

참고

https://sanghaklee.tistory.com/57

RESTful API 설계 가이드

https://kbs4674.tistory.com/118

캐치딜 백엔드 개발이야기 : Restful API 설계의 다양한 고민