시작

API 문서를 만들기 전에 REST 규약에 대한 개념을 정리하고, 더 나은 API 설계를 하기 위해 정리

REST API의 개념

REST API의 개념을 이해하기 위해서 REST의 의미와 API의 의미를 각각 구분

1. REST
   REST는 Representational State Transfer라는 용어의 약자로서 2000년도에 로이 필딩 (Roy Fielding)의 박사학위 논문에서 최초로 소개됨. 로이 필딩은 HTTP의 주요 저자 중 한 사람으로 그 당시 웹(HTTP) 설계의 우수성에 비해 제대로 사용되어지지 못하는 모습에 안타까워하며 웹의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표

2. API
   API란 Application Programming Interface의 약자로 프로그램을 실행하는 인터페이스이다. API를 통해 프로그램에 요청을 전달하기위한 통로 혹은 방법으로 생각하면 됨.

결론적으로 REST API란, URI로 자원(Resource)를 요청하여 특정 형태로 표현(Representation) 한다는 것과 HTTP Method를 적극적으로 활용하여 행위(Verb)를 나타내는 것이다.

REST API의 규칙

REST API 설계 시 가장 중요한 항목은 다음의 2가지로 요약가능하다.

첫 번째, URI는 정보의 자원을 표현해야 한다.
두 번째, 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

예시)

:id와 같이 변하는 값은 하나의 특정 resource를 나타내는 고유값이어야 함.

1. URI는 정보의 자원을 표현해야 한다. (리소스명은 동사보다는 명사를 사용)

GET /members/delete/1

위의 예시는 REST 규칙을 제대로 적용하지 않은 URI로 URI는 자원을 표현하는데 중점을 두고 delete와 같은 행위에 대한 표현이 들어가서는 안된다.

2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)으로 표현

위의 잘못된 URI를 제대로 표현하면 다음과 같이 변경할 수 있다.

DELETE /members/1

3. URI에는 '복수명사'만을 사용하여 간결함을 유지해야 한다.

URI에는 '단수명사'와 '복수명사'를 섞어서 사용하지 않고, '복수명사'만을 사용하여 간결함을 유지해야 한다.

잘못된 예 : /user/8, /item/5
올바른 예 : /users/8, /items/5

4. 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용

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

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

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

6. 하이픈(-)은 URI 가독성을 높이는데 사용한다.

불가피하게 긴 URI경로를 사용하게 된다면 하이픈을 사용해 가독성을 높일 수 있습니다.

7. 밑줄(_)은 URI에 사용하지 않는다.

밑줄은 보기 어렵거나 밑줄 때문에 문자가 가려지기도 합니다. 이런 문제를 피하기 위해 밑줄 대신 하이픈(-)을 사용하는 것이 좋습니다. (가독성)

8. URI 경로에는 소문자가 적합하다.

URI 경로에 대문자 사용은 피하도록 해야 합니다. 대소문자에 따라 다른 리소스로 인식하게 되기 때문입니다. RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 때문이지요.

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

http://restapi.example.com/members/soccer/345/photo.jpg (X)

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

GET / members/soccer/345/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg

그 외 규칙

1. 리소스 관계 표현하기
2. Header 설정하기
3. HTTP 상태코드 반환하기
4. 페이징
5. 정렬, 필터링, 필드 선택
6. 버전관리

위의 항목에 해당하는 규칙들은 프로젝트를 진행하며 필요한 부분만 참고 자료들을 확인하면서 규칙을 지켜 설계하면 된다.

참고자료

• RESTful한 API 설계 방법이 담겨있는 블로그
  https://velog.io/@couchcoding/%EA%B0%9C%EB%B0%9C-%EC%B4%88%EB%B3%B4%EB%A5%BC-%EC%9C%84%ED%95%9C-RESTful-API-%EC%84%A4%EA%B3%84-%EA%B0%80%EC%9D%B4%EB%93%9C

• RESTful한 API 설계 방법과 그 외 규칙에 대한 정보가 담겨있는 블로그
  https://pronist.dev/146