이 글은 지난 번 참고자료에 더하여 마이크로소프트 공식문서를 참고해서 작성했습니다.

그리고 튜터님께 확인 결과 REST API의 URI에서 동사를 쓰지 않고, 명사를 쓰는 이유는 보안 이유와 아무 관련이 없다고 이야기를 들었고, 마이크로소프트 공식 문서에는 "가능하다면" 동사 쓰지 말고 명사를 쓰라고 되어 있습니다.

그리고 roy fielding의 논문에서 REST 개념을 설명하는 챕터에서도 동사/명사 내용은 나오지 않습니다. 참고 바랍니다.

REST API란?

REST API는 2000년 Roy Fielding 박사 2000년에 제시한 Representational State Transfer 아키텍쳐를 사용해 API를 설계한 것이다.

필자는 REST API를 조사 해본 결과, 현업에서 사용되는 REST API는 Roy Fielding 박사가 제사한 REST 개념과는 다소 차이가 있다는 걸 알았으며, 튜터님께도 이 사실을 확인 받았다.

그래서 염격한 REST 개념을 아는 것보다 현재 개발자들이 어떻게 REST API를 설계하는지가 우리에게 더 중요한 것 같아서 현재 실무자들이 사용하는 REST API 개념 위주로 작성했다.

REST API의 특징.

URI와 HTTP Method만으로도 어떤 자원을 가지고 어떤 동작을 취하려는지 유추할 수 있다. 그래서 잘 만들어진 Rest API는 URI만으로도 API 사용에 대해 많은 정보를 알 수 있다.

출처: 통통코딩

REST API 설계 규칙

1. 리소스를 중심으로 API를 설계하라.

예시1 한 학교의 교실 명단을 가져오는 API를 만든다고 가정하자. 학교 전체 교실 정보를 담은 HTTP GET request식의 API를 만들면 된다.

GET https://nbcamp.com/classes

JSON 포맷으로 받으면 아래와 같이 리로스를 받아 올 것이다.

{
"result": [ 
	    {"idx": 1, "class": "1반"}, 
            {"idx": 2, "class": "2반"}, 
            {"idx": 3, "class": "3반"},
           ]
}

여기서 2반의 정보를 가져오고 싶으면 다음과 같이 작성한다.

GET https://nbcamp.com/classes/2

여기서 다시 2반의 학생 명단을 가져오고 싶으면 아래와 같이 작성한다.

GET https://nbcamp.com/classes/2/students

JSON 포맷으로 받아오면 아래와 같이 보일 것이다.

{
"result": [ 
	    {"idx": 1, "name": "홍찬양"}, 
            {"idx": 2, "name": "은지김"}, 
            {"idx": 3, "name": "진호장"},
           ]
}

여기서 다시 번호가 3번인 학생의 정보를 가져오고 싶으면 아래와 같이 작성한다.

GET https://nbcamp.com/classes/2/students/3

{
"result": [ 
	    {"idx": 3, "name": "진호장"}
           ]
}

보다시피 URI와 HTTP Method 만으로 어떤 자원이며 어떤 동작을 할지 유추가 가능하다.

*참고로 스파르타코딩클럽 원격 강의 내용을 보면 "/api/courses" 처럼 api를 붙이는 경우를 봤을 텐데, 이는 api라는 것을 쉽게 알기 위함이다.

실제 API에서는 URI에 "api"단어가 없다는 것을 알 수 있다.

https://www.googleapis.com/books/v1/volumes?q=search+terms

구글 책 API인데, URI에 "api"단어가 없는 것을 알 수 있다.

이 부분은 개발자들끼리 정하면 될 것 같다.

2. Collection은 복수로 표현, Item/Element는 단수로 표현.

위의 예시에서 보면 topics라는 컬렉션은 topics로 복수로 표현한다. 그리고 element 혹은 item인 rest는 단수로 표현한다.

3. 동사 사용을 지양하고, 가능하면 명사만 사용해서 URI를 표현한다.

출처: https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design

API가 무엇을 하는지는 HTTP Method (GET, POST, DELETE, PUT, PATCH) 를 통해서 안다.

위의 예시처럼 URI에서 create-list, update-profiles 표현 대신 POST /list, PUT /profiles 이런 식으로 표현한다.

스프링에서는 아래와 같이 코드를 작성한다.

4. '/'는 계층 관계를 나타내는데 사용.

https://nbcamp.com/classes

https://nbcamp.com/classes/students

5. URI의 마지막 문자로 '/'를 포함하지 않는다.

https://nbcamp.com/classes/students/ X

https://nbcamp.com/classes/students O

6. 긴 URI에서 불가피하게 특수문자 '-' 사용해야 한다면, 가독성을 위해서 '-'를 사용하고, 언더스코어인 '_'는 지양하자.

https://career.guru99.com/category/heavy_industries X

https://career.guru99.com/category/heavy-industries O

대쉬 사용을 지양한다고 무조건 안 쓰면 안된다. 위의 예시에서 heavy industry(중공업)은 원래 2개의 단어로 구성 되어있다.

https://career.guru99.com/category/heavyindustries

무작정 대쉬 사용 피하기로 위와 같이 작성하면 오히려 가독성이 떨어진다.

될 수 있으면 지양하되, 필요하면 적절하게 쓰자.

7. URI는 대문자 말고 소문자 사용.

8. REST API로 데이터를 주고 받을 때 사용할 수 있는 포맷은 Text, XML, JSON이 있으며, 주로 JSON을 많이 사용함.

JSON을 주로 사용하는 이유는 여기에 적혀있다.

9. REST API에서는 주로 쓰이는 HTTP Method는 GET, POST, PUT, DELETE, PATCH임.

GET - read,

POST - create,

DELETE - delete,

PUT - 정보를 통째로 수정할 때,

PATCH - 정보 중 특정 부분을 수정할 때.

PATCH의 예시.
- 이름: 호성우,
- 성별: 남자,
- 팀: 1
  - 팀 1 - > 2 로 수정할 때.

REST아키텍쳐는 제약(조건)

Uniform Interface 균일한 인터페이스

리소스 식별
Representation을 통한 리소스 조작
자체 설명 가능한 메시지 (Self-Descriptive Message)
Application State 엔진으로서 Hypermedia

Stateless 스테이트리스

Cacheable 캐싱 가능성

Client-Server 독립

Layered System 계층구조적 아키텍쳐

Code on Demand (선택사항, 옵션)

실무에서 쓰이는 REST API에서 REST 아키첵쳐의 특징을 가져다 쓴 것 중 가장 두드러지는 부분은 "균일한 인터페이스"의 "자체 설명 가능한 메시지"이다.

그 다음으로 중요한 특징이 stateless와 client-server의 독립성이다.

* 여담으로 Roy Fielding의 REST를 제대로 지키면서 REST API를 작성하는 개발자는 많지 않을 것 같다. Roy Fielding 박사의 블로그에 보면 "난 다수의 사람들이 아무 HTTP기반 API를 Rest API라고 부르는 것에 좌절하고 있다."라고 적혀있다. 그래서 너무 REST 아키텍쳐가 뭔지 아는 것보다는 대략 REST API는 이렇게 생겼고, 이렇게 설계하고 나머지는 같이 일하는 개발자들이나, 자신의 속한 조직의 코드 컨벤션에 따라서 맞춰 쓰면 되지 않을까 개인적으로 생각한다.

참고자료:

쉽고 한번에 이해하고 싶다면

https://bit.ly/2YenGcd

https://bit.ly/3kagvt5

REST 아키텍쳐에 대한 설명

https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

REST API에 대한 설명

https://www.ibm.com/kr-ko/cloud/learn/rest-apis

https://www.redhat.com/ko/topics/api/what-is-a-rest-api

https://meetup.toast.com/posts/92

REST API 설계에 대한 설명

https://meetup.toast.com/posts/92

https://spoqa.github.io/2012/02/27/rest-introduction.html

https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design

'스파르타코딩 내일배움캠프' 카테고리의 다른 글

내일배움캠프 Day 58 - 스프링 실시간 수업 5일차 (0)	2021.11.10
내일배움캠프 Day 57 - 스프링 실시간 수업 4일차 (0)	2021.11.08
내일배움캠프 - Day 54 (0)	2021.11.05
내일배움캠프 - Day 53 (0)	2021.11.05
내일배움캠프 - Day 52 - 실시간 수업 6일차 - 스프링 1일차 (0)	2021.11.03

지(智)를 사랑하는 개발자

내일배움캠프 Day 56 - REST API 수정

REST API란?

REST API의 특징.

REST API 설계 규칙

1. 리소스를 중심으로 API를 설계하라.

2. Collection은 복수로 표현, Item/Element는 단수로 표현.

3. 동사 사용을 지양하고, 가능하면 명사만 사용해서 URI를 표현한다.

4. '/'는 계층 관계를 나타내는데 사용.

5. URI의 마지막 문자로 '/'를 포함하지 않는다.

6. 긴 URI에서 불가피하게 특수문자 '-' 사용해야 한다면, 가독성을 위해서 '-'를 사용하고, 언더스코어인 '_'는 지양하자.

7. URI는 대문자 말고 소문자 사용.

8. REST API로 데이터를 주고 받을 때 사용할 수 있는 포맷은 Text, XML, JSON이 있으며, 주로 JSON을 많이 사용함.

9. REST API에서는 주로 쓰이는 HTTP Method는 GET, POST, PUT, DELETE, PATCH임.

REST아키텍쳐는 제약(조건)

참고자료:

'스파르타코딩 내일배움캠프' 카테고리의 다른 글

티스토리툴바

내일배움캠프 Day 56 - REST API 수정

REST API란?

REST API의 특징.

REST API 설계 규칙

1. 리소스를 중심으로 API를 설계하라.

2. Collection은 복수로 표현, Item/Element는 단수로 표현.

3. 동사 사용을 지양하고, 가능하면 명사만 사용해서 URI를 표현한다.

4. '/'는 계층 관계를 나타내는데 사용.

5. URI의 마지막 문자로 '/'를 포함하지 않는다.

6. 긴 URI에서 불가피하게 특수문자 '-' 사용해야 한다면, 가독성을 위해서 '-'를 사용하고, 언더스코어인 '_'는 지양하자.

7. URI는 대문자 말고 소문자 사용.

8. REST API로 데이터를 주고 받을 때 사용할 수 있는 포맷은 Text, XML, JSON이 있으며, 주로 JSON을 많이 사용함.

9. REST API에서는 주로 쓰이는 HTTP Method는 GET, POST, PUT, DELETE, PATCH임.

REST아키텍쳐는 제약(조건)

참고자료:

'스파르타코딩 내일배움캠프' 카테고리의 다른 글

'스파르타코딩 내일배움캠프' Related Articles

티스토리툴바