Restful한 api는 무엇일까

     

목차

 

 

참고

간단한 정의는 아래 블로그를 참고하면 좋을 것 같습니다.

https://hahahoho5915.tistory.com/54

[간단정리] REST, REST API, RESTful 특징

 

이번 글의 목적은 api를 짜는 과정을 보면서 일관성이 없다는 것이 느껴져서 이참에 보편적인 api 사용에 대해 정의해 보고자 한다.

 

restful api 설계 규칙

1. 슬래시 구분자는 계층 관계를 나타내는데 사용한다.

ex) http://restapi.local.com/department/member

 

2. url 마지막 문자로 슬래시를 포함하지 않는다.

ex) http://restapi.local.com/department/member/ -> x

 

3. 하이픈은 url 가독성을 높이는데사용한다. 단 _은 url에 사용하지 않는다.

ex) http://restapi.local.com/department/member-1

http://restapi.local.com/department/member_1  -> x

 

4. url 경로에는 소문자를 사용한다.

RFC 3986(url 문법 형식) 은 url  스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정한다.

 

5. 파일 확장자는 url에 포함하지 않는다.

ex) http://restapi.local.com/department/member/image.png -> x

 

6.리소스 간의 연관 관계가 있는 경우 아래와 같은 형식을 사용한다.

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

 

 

GET 요청 메소드 처리

쿼리 파라미터 vs 패스 파라미터

 

패스 파라미터란?

url을 통해 고유한 자원을 지칭하기 위해 사용한다.

ex) http://naver.com/stocks/uber

 

 

 

쿼리 파라미터란?

url에 특정한 조건을 주고 싶을 때 사용하는 매개변수 유형

url 끝에 물음표 뒤에 나타나며 and 기호(&)로 구분된 이름=값 쌍으로 구성

 

쿼리 파라미터 사용 에시

• 데이터 필터링
• 데이터 정렬
• 데이터 수 조절 (페이지네이션)
• 검색

 

대표 예시

[GET] /products?price=3000

[GET] /products?ordering=-id

[GET] /products?offset=0&limit=100

[GET] /products?serach=홍길동

 

그렇다면 위 변수들을 request body에 넣고 요청할 수 있지 않을까? 라고 생각이 들 수 있다.

데이터를 표현하는 HTTP method는 [GET]이고 GET method에서는 request body를 사용하지 않는 것이 권장된다.

 

DELETE 요청 메서드 처리

이번 프로젝트의 api 명세를 보면서 body에 id를 넘겨주는 부분이 있어 delete에 body를 쓰는 것이 적합한지 의문이 들었다.

 

DELETE 메서드는 HTTP 표준에서 요청 본문(Request Body)을 포함하지 않아도 되도록 정의되어 있다. 따라서 DELETE 메서드 요청에는 일반적으로 요청 본문이 포함되지 않는다.

 

따라서 roomId는 패스 파라미터에 추가하고

인증정보는 헤더에 넣는 것이 맞다.

 

ex) delete -> http://restapi.local.com/department/1

 

 

POST, PUT, PATCH 메서드 차이점

POST

POST의 특징은 멱등성(idempotentency)이 없다는 점이다. 

예를 들어, 같은 내용의 요청을 /pays로 3번 보내면 /pays/1, /pays/2, /pays/3와 같이 똑같은 데이터를

가진 리소스 3개가 생성된다.

그 후 서버는 /pays 아래에 /pays/1와 같이 새로운 리소스를 만든다. POST 메서드로 리소스를 생성하면 서버에서 정의한 로직대로 리소스의 URI(및 ID)를 발급한다.

 

PUT

 PUT 메서드는 주로 리소스를 업데이트할 때 사용한다. 리소스 업데이트할 때는 이미 생성된 리소스의 정확한 URI를 알고 있고, 안전하게 멱등한 요청을 보내고 싶기 때문이다. 그러나 PUT 메서드는 리소스 전체를 업데이트해야 된다는 특징이 있다. 즉, 리소스 일부만 수정하고 싶어도 전체 필드 데이터를 요청 본문에 포함해야 한다.

 

PATCH

PATCH 메서드도 PUT 메서드와 같이 특정 리소스 URI를 정확히 알고 있어야 된다. 그러나 PUT은 서버에 있는 리소스를 완전히 대체하지만, PATCH는 클라이언트의 요청에 따라 리소스를 수정하고 부분 업데이트를 한다.

 

 

 

api 명세 무엇들이 들어가야 할까?

api 소개

단순히 API에 대한 기능 설명을 하는 것 보다는 API의 개발 배경, 비즈니스 목적, 장점 등을 포함한다면 외부 개발자는 API를 좀 더 명확히 이해하는데 도움이 될 것이다.

 

공통 요청/응답 형식

개요에 해당 API의 공통된 요청과 응답 형식을 정리하면 독자는 API를 어떻게 접근할지 파악할 수 있습니다. 또한 동일한 내용을 각각의 API의 상단에 반복하여 작성하지 않아도 되기 때문에 가독성 있는 문서를 만들 수 있다.

 

공통 에러

문서의 한 섹션에 공통 에러를 제공하면 각 API에 에러 코드를 각각 추가하지 않아도 되고, 변경도 한 곳에만 하면 되니 테크니컬라이터 입장에서는 문서 정합성 유지에도 큰 도움이 된다.

 

 

 

결론

api 명세서는 백엔드 혼자서만이 아니라 프론트와 백엔드가 바라보는 관점이 다르기 때문에 함께 의논하고 짜는 것이

추후 수정이나 의견 제시에서 좋은 것 같다.