Restful API 문서 작성
Rest(Representational State Transfer)란, HTTP에서 필요한 자원에 접근할때 웹의 장점을 최대한 활용하기 위한 아키텍쳐
Resources(URIs)
Names
리소스들의 묶음을 묘사하기 위해 동사가 아닌 복수명사를 사용한다. 여기서 복수명사는 리소스의 collection을 뜻한다. collection의 각 요소를 element라고 한다. 주로 id값을 엘리먼트 값으로 사용한다. 클라이언트는 다음과 같은 요청을 보내는데, method/collection/element와 같이 작성된다.
따라서, 요청문만 보더라도 어떤 동작이나 정보를 위한 것인지를 바로 추론할 수 있다.
Post/users
POST/classes/2/students
GET/users
GET/users/1234
PATCH/users/2
PUT/users/2
Delete/addresses/1234리소스 간 관계
리소스 간 관계가 있을때, URI로 표현할때에는 method/parent_collection/parent_element_id/child_collection로 작성한다.
GET/topics/1/commentsURI case
프로그래밍에서 리소스 네이밍을 할때 다음과 같은 세가지 컨벤션이 있다: CamelCase, snake_case, 그리고 spinal-case.
CamelCase
먼저 CamelCase는 자바에서 자주 사용하며, 각 단어의 시작을 강조해 대문자로 표현한다. 하지만, 대소문자가 구분되지 않는 경우(case insensitive) 효과적이지 않다.
snake_case
C언어 프로그래머들에 의해 오랫동안 사용되어왔고, 최근에는 루비에서도 사용된다. 단어들은 언더스코어 "_"로 구분되어 컴퓨터 컴파일러 또는 인터프레터로 하여금 하나의 심볼로 이해하도록 하지만, 읽는 이로 하여금 두 단어로 쉽게 구분할 수 있도록 한다. 하지만, snake_case는 C 프로그램에서 발생한 잦은 남용으로 사용량이 많이 줄고있다.
spinal-case
spinal-case는 하이픈을 사용해 두 단어를 분리한다. 이때의 장단점은 snake_case와 유사하지만, 몇몇의 프로그래밍 언어에서는 변수명, 클래스, 함수명 등에 하이픈을 허용하지 않는다는 점이 다르다. RFC3986에 따르면, spinal-case를 쓰는 것이 권장되며, 구글, 페이팔 등 대기업에서 사용하고 있다.
HTTP methods
-
GET
주어진 URI에 저장된 데이터 정보를 가져올때(retrieve) 사용된다. GET 요청은 데이터를 가져오기만 할뿐, 해당 데이터를 변경하거나 추가하지 않는다. -
HEAD
GET과 유사하지만, HEAD 요청에 대한 응답은 본문을 가져선 안된다. GET 요청을 보냈을때 돌아올 헤더를 요청하는 메소드이다. -
POST
서버로 데이터를 전송할때 사용된다. -
PUT
타겟 리소스를 새로운 데이터로 모두 변경할 때 사용된다. -
PATCH
리소스의 일부를 업데이트할때 사용되며, 멱등성이 필요하지 않다.
멱등성이란, 동일한 요청을 **한번 **보내는 것과 **여러번 연속으로** 보내는 것이 같은 효과를 지니고, 서버의 상태도 동일하게 남을때, HTTP 메서드가 멱등성을 가졌다고 말한다. POST와 PATCH는 멱등성을 갖지 않는다. -
DELETE
주어진 URI의 모든 리소스를 삭제한다. -
OPTIONS
타겟 리소스의 커뮤니케이션 옵션을 묘사한다.
Query parameters
- Paging
- Searching
- Filtering
구체적인 특징, 속성등으로 쿼리된 리소스의 개수를 제한한다. 한번에 여러개의 속성으로 필터링할 수 있다. - Sorting
리소스 콜렉션을 분류한다. 분류 파라미터는 분류가 될 속성 이름들을 포함해야하며, 쉼표로 구분된다.
예시
https://www.googleapis.com/books/v1/volumees?q=search+terms
잘 작성된 api는 url만 보더라도 다음의 세가지 내용을 통해 요청내용을 짐작할 수 있다.
- http method
- url 데이터 접근
- representation 자원의 표현
reference
