REST API

API

A pplication
P rogramming
I   nterface

API란 프로그램의 커뮤니케이션을 담담하는 도구로써
프로그램이 다른 프로그램을 이용할 때, 사용하는 인터페이스입니다
데이터로 이루어져 있으며, 사람이 아닌 프로그램을 위한 인터페이스

인터페이스는 사람과 프로그램으로 치면 키보드, 마우스, 모니터등 ....

---

REST

R epresentational
S tate
T ransfer

웹의 장점을 최대한 활용할 수 있는 아키텍쳐로써
2000년도 로이필딩의 박사학위 논문에서 REST가 처음으로 발표되었다

구성

1. 자원 ( Resource ) - URI
2. 행위 ( Verb ) - HTTP Method
3. 표현 ( Representation )

특징

1. Uniform ( 유니폼 인터페이스 )

URI로 지정한 리소스에 대해 조작을 통일하고
한정적인 인터페이스로 수행하는 아키텍쳐 스타일

URI = URN + URL
Uniform Resource Identifier
인터넷에 있는 자원을 나타내는 유일한 주소이다.
URI의 존재는 인터넷에서 요구되는 기본조건으로서 인터넷 프로토콜에 항상 붙어 다닌다.

2. Stateless ( 무상태성 )

REST는 무상태성을 가짐, 작업을 위한 상태정보를 따로 저장하고, 관리하지 않음
세션정보나 쿠키정보로 저장하고 관리하지 않기 때문에 API서버는 들어오는 요청만
단순하게 처리하면 됨
이렇게 관리를 함으로써 서비스의 자유도가 높아지고, 서버에서 불필요한 정보를
관리하지 않게 되면서 구현이 단순해 짐

3. Self Discriptiveness ( 자체 표현 구조 )

Rest api의 메시지만 보고도 이를 쉽게 이해할 수 있는 자체 표현구조로 되어있음

api 서버의 리소스를 보게 되면 명사로 되어있고, 굉장히 직관적인 걸 볼 수 있는데

{version}/dongne/dongneForecast

이 api는 apistore란 곳에서 가지고 온 주소인데 주소만 봐도 어떤 걸 표한하는지
한눈에 보인다

GET, POST, PUT, DELETE 등..
메서드 또한 어떤 용도로 사용하는지 한눈에 보이기 때문에 자체 표현구조라는 특징을 갖는다

메시지 또한 JSON을 이용해서 직관적으로 이해가 가능하다

4. Client - Server 구조

Server는 api를 제공
Client는 사용자 인증이나, 컨텍스트 등을 직접 관리

각각의 역할이 명확하게 구분이 되어있기 때문에 Client와 Server에서 각자
개발해야 할 내용이 명확해지고 서로간의 의존성이 줄어들게 됨

5. Cacheable ( 캐시 가능 )

HTTP라는 기존 웹표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를
그대로 활용이 가능하다

6. 계층형 구조

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

계층을 추가한다...

비지니스 로직만을 수행하는 api서버
그 앞단에는 유저를 인증하는 계층, 암호화 등등
서버를 관리하는데 있어 필요한 계층을 추가 함으로써 유연성을 가진다

---

REST API 디자인 가이드

URI는 정보의 자원을 표시해야함
자원에 대한 행위는 HTTP method로 표현해야함

리소스 명은 동사보다는 명사를 사용

api/v1/products
api/v1/users
api/v1/stories

등등 명사를 사용해 준다

메서드

HTTP에는 여러가지 메서드가 있지만,
REST에서는 CRUD에 해당하는 4가지의 메서드만 사용한다

POST = Create
GET = Read
PUT = Update
DELETE = Delete

슬래시는 계층 관계를 나타내는데 사용

posts/create
users/login
users/logout

등등 서로간의 관계를 나타낼 때 사용한다

URI의 마지막 문자로 슬래시를 포함하지 않는다

슬래시는 식별자로써의 역할만 합니다

하이픈은 가독성을 위해서 사용

너무 긴 URI를 사용 할 경우 -을 이용하여 가독성을 높여준다

언더바 "_" 는 사용하지 않는다

이것또한 가독성 때문입니다

URI의 경로로는 소문자를 사용한다

리소스의 경우 대문자와 소문자를 구분하기 때문에
소문자를 사용해 줍니다

파일확장자는 URI에 포함하지 않는다

REST API에서는 메시지의 파일 포맷을 나타내기 위한 파일 확장자는
URI에 포함시키지 않습니다

Accept Header를 사용하여 표현해 준다

query parameter

products/sort=name
rooms/sort=price

등등 쿼리파라미터는 정렬 혹은 필터링을 할 경우에 사용한다

안좋은 예로는 메서드를 쿼리파라미터로 보내는 것인데

users/method=post
products/method=update/name=note

이런식으로 메서드를 포함하는 경우

REST API의 status-code

2XX

200 ok

클라이언트로부터의 요청이 성공적으로 처리 되었음을 나타냄

201 created

새로운 리소스가 생성 되었음을 나타냄
200과 비슷하지만 201의 경우는 무언가 생성이 성공했음을 나타낸다
조금더 정확한 표시를 위해 사용

202 Accepted

클라이언트의 요청은 정상적이나, 서버에서 아직 처리하지 못햇을 경우
비동기프로그래밍에서 작업이 아직 완료되지 않았을 경우
조금더 기다리라는 의미에서 이 메시지를 나타내줌

4XX

클라이언트의 요청이 유효하지 않아 서버에서 요청을 처리 하지 않는 경우

400 Bad Request

클라이언트의 요청이 유효하지 않아 더 이상 작업을 진행하지 않는 경우

401 Unauthorized

클라이언트가 인증이 안된경우

로그인을 안한경우가 대표적인 예시

403 Forbidden

클라이언트가 권한이 없는 경우

401과 굉장히 헷갈렸는데 둘 유저의 권한이 없을 때 사용하는 것으로 알았다

만약 어떤 페이지에 들어가서 글을 읽으려는데
Anonymous user인 경우 글을 읽지 못하게 설정해 놓았다면
여기서 사용하게 될 응답 코드는 401

이제 로그인을 진행하고 글을 쓰려고 하는데
레벨이 부족해서 글을 작성하지 못하는 경우 응답코드는 403

404 Not Found

클라이언트가 요청한 자원이 존재하지 않을 경우

경로 = 자원이 존재하지 않을 경우

5XX

서버 오류로 인해 요청을 수행할 수 없는 경우

Client에게 직접적으로 보이면 안되는 상태 코드이다

RESTful API

RESTful API는 이런거다 정의하기 보다는 각자가 생각하는게 조금씩은 다를 것 같다

하지만 기본 베이스는 스타일가이드를 따르고, 안좋은 예시가 있다면 그렇게 안하는게 아닐까샆다

REST를 더욱더 REST답게 사용하는 것

---

출저
https://meetup.toast.com/posts/92 restapi
https://sanghaklee.tistory.com/61 status code