2023.05.16 - REST API

오늘, 어제 작성한 S.A에 피드백이 들어왔다.

 

여러가지 피드백이 있었지만, API명세에 관한 부분이 눈에 띄어 REST API를 공부하게 됐다.

 

 

참고 링크 : 

https://aws.amazon.com/ko/what-is/restful-api/

RESTful API란 무엇인가요? - RESTful API 설명 - AWS

https://dzone.com/articles/7-rules-for-rest-api-uri-design-1

7 Rules for REST API URI Design - DZone

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

REST API 제대로 알고 사용하기 : NHN Cloud Meetup

 

 

1. REST API??

REST는 Representational State Transfer 의 약자입니다.

 

2. REST 구성

• 자원(RESOURCE) - URI
• 행위(Verb) - HTTP METHOD
• 표현(Representations)

 

3. REST의 특징

3-1) Uniform(유니폼 인터페이스) : 일관적인 인터페이스로 분리되어야 한다.

3-2) Stateless(무상태성) : 작업을 위한 상태정보를 따로 저장하고 관리하지 않는다.

3-3) Cacheable(캐시 가능성) : 서버 응답 시간을 개선하기 위해 클라이언트 또는 중개자에 일부 응답을 저장하는 프로세스인 캐싱을 지원한다.

3-4) 계층화 시스템 : REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 한다.

3-5) Code on demand : 서버는 소프트웨어 프로그래밍 코드를 클라이언트에 전송하여 클라이언트 기능을 확장할 수 있다.

 

 

---

 

REST API 설계 가이드

 

첫 번째, URI는 정보의 자원을 표현해야 한다. 

두 번째, 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

 

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

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

 

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

대소문자에 따라 다른 리소스로 인식하기 때문에 최대한 대문자는 피해야 한다.

http://restapi.example.com/Memeber (X)

 

3. URI의 마지막에 슬래시(/)는 사용하지 않는다.

URI의 모든 문자는 리소스의 ID로 사용하기 때문에 혼동을 피하기 위해 / 는 사용하지 않는다.

http://restapi.example.com/members/ (X)

 

4. _(언더바)는 URI 사용하지 않는다.

글꼴에 따라 언더바가 보이지 않거나 가려질 수 있기 때문에 문제를 피하기 위해 사용하지 않는다.

http://restapi.example.com/members/user_collection (X)

5. -(하이픈)은 URI의 가독성을 위해 사용한다.

만약 URI가 길어진다면 -(하이픈)을 사용해 가독성을 좋게 한다.

http://restapi.example.com/members/user-collection (o)

6. 계층 구조를 나타내기 위해 /를 사용한다.

http://restapi.example.com/zoo/animals/whales

 

7. URI에 작성되는 영어를 복수형으로 한다.

URI의 형식을 일관되게 유지하기 위해 복수형으로 사용한다.

http://restapi.example.com/zoo/animals/whales (o)

http://restapi.example.com/zoo/animals/whale (x)