[Network] 나는 지금 RESTful API를 만들고 있을까?

 

 

 

많은 회사들의 백앤드 채용 시 자격요건에 항상 들어가는 문구 중 하나가 있다.

 

RESTful API에 대한 설계 및 개발 경험이 있으신 분

 

나는 프로젝트를 진행하면서 RESTful 하게 API를 만들고 있는지 궁금했다. 심지어 2023년에 REST에 관한 포스팅을 하고  정작 코드에 적용을 안 한 것 같다. 이번 기회에 예제에 초점을 맞춰서 정리도 하고, 프로젝트에 수정하려고 한다.

 

 

 

 

 

 

[REST, REST API, RESTful API 개념]

 

 

아래 링크를 통해 개념을 정리하고 오자.

 

 

https://run-ran-run-ant.tistory.com/40

[Network] REST, REST API, RESTful

 

 

 

 

 

 

[RESTful API 만들기]

1. URI는 정보의 자원을 표현해야 한다.

    - 리소스 명은 동사보다는 명사를 사용하자.

GET /user/select/1  (X)
GET /user/insert/1  (X)
GET /user/delete/1  (X)

 

 

    - 단수 명사 대신 복수 명사를 사용하자. (단수, 복수를 섞어서도 사용 X)

GET /users/1 (O)

 

 

 

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

    - 위 예시를 HTTP Method를 적용해 보면 아래와 같다.

//정보 가져올 때
GET /user/1   (O)
	
//회원 정보 추가할 때
POST /user    (O)
	
//삭제시
DELETE /user/1 (O)

 

 

 

 

3. 슬래시(/)는 계층 관계를 나타내는 데 사용한다.

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

//프로젝트 -> 이미지 관련 행위
http://restfulapi.sample.com/projects/files/images/   (X)

http://restfulapi.sample.com/projects/files/images    (O)
	
//프로젝트 -> 동영상 관련 행위
http://restfulapi.sample.com/projects/files/videos    (O)

 

 

 

 

4. 가독성을 위해 밑줄(_) 대신 하이픈(-)을 사용하자.

    - 밑줄(_)은 보기가 어렵고, 가져질 수 있으므로 URI가 길어질 경우는 하이픈(-)을 이용하는 게 읽기가 편하다.

http://restfulapi.sample.com/projects/post_images   (X)
http://restfulapi.sample.com/projects/post-images   (O)

 

 

 

 

5. URI 경로에는 소문자를 사용하자.

    - RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외한 나머지는 대소문자를 구별하도록 규정한다. 따라서 URI 경로는 대문자 대신 소문자를 사용하도록 한다.

//아래 두 URI는 서로 같게 인식한다. 
//호스트에서는 대소문자를 구별하지 않기 때문이다.
http://restfulapi.sample.com/projects/post-images
HTTP://RESTFULAPI.SAMPLE.COM/projects/post-images

//아래 두 URI는 서로 다른 URI이다. 
//호스트 뒤로 붙는 path가 대소문자로 구분되기 때문이다.
http://restfulapi.sample.com/projects/post-images
http://restfulapi.sample.com/projects/Post-images

//참고
http://restfulapi.sample.com/projects/postImages   (X)
http://restfulapi.sample.com/projects/post-images  (O)

 

 

 

 

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

http://restfulapi.sample.com/projects/files/images/sample.jpg   (X)

 

 

REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다.
Request의 헤더에 Accept 속성을 통해 파일 형식을 지정해 주자.

 

http://restfulapi.sample.com/projects/files/images/sample    (O)
HTTP/1.1 HOST: restfulapi.sample.com Accept: image/jpg

 

 

 

 

7. 컨트롤(Control) 자원인 경우에만 예외적으로 동사 사용을 허용한다.

    - HTTP Method(GET, POST, PUT, PATCH, DELETE)로 표현되는 행위 외에 다른 행위를 표현해야 하는 경우 허용한다.

http://restfulapi.sample.com/projects/files/duplicating  (X)
http://restfulapi.sample.com/projects/files/duplicate    (O)

 

 

 

  - GET, POST만 사용할 수 있는 HTTP FORM의 경우 컨트롤 URI(동사로 된 리소스 경로)를 사용한다.

http://restfulapi.sample.com/projects/files/new       (O)
http://restfulapi.sample.com/projects/files/play      (O)
http://restfulapi.sample.com/projects/files/delete    (O)

 

 

 

 

 

 

 

[느낀 점]

REST에 관한 포스팅을 한 후 다른 프로젝트를 진행하면서 점점 REST에 익숙해져서 그런지 처음 포스팅 할 때 보다 내가 어느 부분을 수정해야겠는지 많이 와닿았다. 그리고 이렇게 규칙에 맞게 작성하면 클라이언트와 서버가 서로 종속적이지 않게 된다는 장점도 알게 됐다. 

 

개념을 잘 알고, 잘 사용해서 누구나 봐도 이해하기 좋은 코드가 되게 노력해야겠다:)

 

 

 

 

 

 

 

[참고]

https://sanghaklee.tistory.com/57

https://one-it.tistory.com/entry/RESTful-API-%EC%84%A4%EA%B3%84-%EA%B7%9C%EC%B9%99