REST API, API 문서

※이 포스팅은 sopt 26기 server part seminar 자료 바탕으로 작성되었으며, 복습용입니다.

1-1. URI, URL

URI	URL
통합 자원 식별자 자원을 나타내는 주소	통합 자원 지시자
고유하게 정보 리소스를 식별하고 위치를 지정 어떤 자원의 위치를  의미하고 HTTP는 주어진 URI로 객체 를 찾아오고 Method가  그 위치에 대한 행위를 뜻함	특정 서버의 한 리소스에 대한 구체적인 위치를 서술 네트워크 상  해당 자원이 어디 있는지 알려주는 규약 어떤 특정 지점의 위치 또는 파일 리소스에 접근하기 위한 주소

즉, URI 는 URL을 포함한 개념

- 네이밍이 직관적이야하고 명사가 이해하기 좋음

- URI 설계에 정답은 없지만 항상 일관된 규칙으로 작성해야 혼동되지 않는다..!

https://github.com/Jeong-Hyowon	URI, URL
https://github.com/	URI, URL
https://search.naver.com/search.naver?sm=top_hty&fbm=1&ie=utf8&query=server	URI URL이 해당되지 않는 이유 (서버 리소스 내의 저장 위치와 상관없는 지정자)

 

728x90

---

2-1. API

API란, 

- 서버 애플리케이션의 기능을 사용하기 위한 방법/수단 

- 구현 방식을 알지 못해도 서비스가 서로 통신 가능

- 리소스에 대한 액세스 권한을 제공하고 보안과 제어를 유지할 수 있게 해주며 액세스 권한을 어떻게, 누구에게 제공할지 여부만 결정하면 됨

- URI는 서버 설계 도면 / API는 서버 사용 설명서

- URI는 서버 구성 요소를 나타냄 (URI와 API 둘 다 명확하고 직관적이여야 타인이 볼 때 헷갈리지 않음)

---

2-2. REST

REST란,

리소스 지향 아키텍쳐로 모든 것을 리소스, 명사로 표현

- 모든 형태의 명령이 명사형으로 정의가 가능한 것은 아니지만, 최대한 리소스 기반의 명사 형태로 정의를 하는게 REST형태의 디자인이 됨

---

2-3. REST API

웹(HTTP) 설계의 우수성에 비해 제대로 사용되어지지 못하는 모습에 안타까워하며 웹의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표

즉, 자원(URI는 정보의 자원을 표현) + 행위(자원에 대한 행위는 HTTP Method (GET, POST, PUT, DELETE 등) 으로 표현)

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

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

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

- 밑줄(_)은 URI에 사용하지 않음

- URI 경로에는 소문자가 적합

- 파일 확장자는 URI에 포함시키지 않음

- 자원을 표현하는 Collection과 Document

(Document는 단순히 문서 - 한 객체 / Collection은 문서들의 집합, 객체들의 집합)

Uniform Interface	URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일
Stateless	HTTP Session과 같은 컨텍스트 저장소에 상태 정보를 저장하지 않음 API 서버는 들어오는 요청 만을 들어오는 메시지로만 처리하면 되며, 세션과 같은 정보를 신경 쓸 필요 없음
Layered System	REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간 매체를 사용할 수 있음
Self-descriptiveness	REST API 메시지만 보고도 API를 쉽게 이해 할 수 있음
Client-Server	REST 서버는 API를 제공하고, 제공된 API를 이용해서 비즈니스 로직 처리 및 저장을 책임짐. 각각의 역할이 확실히 구분되기 때문에 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로간 의존성이 줄어듦
Cacheable	HTTP라는 기존의 웹 표준을 그대로 사용하기 때문에 캐싱 기능 적용 가능

---

3-1. API 명세서

- API 문서는 누가 봐도 이해할 수 명확하고 직관적이여야 한다

- 클라이언트에게 API 명세서를 제공해야함 문서 작성방법에는 다양한 방법(swagger, postman api)가 있지만 스프레드시트나 Github WIKI 추천

API 이름

HTTP Method

Content-Type

Request Header/Body

Response Body

(합동 세미나와 앱잼을 하면서 API 명세서가 정말 중요한 존재였고, 수정할 때 마다 클라이언트한테도 꼭꼭!!!! 수정 사실을 알려줘야한다!!!!!!!!!!!!)