API (Application Programming Interface)란? (= 서버 API)
- API는 한 프로그램이 다른 프로그램을 이용할 때 쓰는 인터페이스로 입출력이 데이터로 됩니다.
- 어떤 특정 사이트에서 특정 데이터를 공유할 경우 어떤 방식으로 요청해야 하는지 어떤 데이터를 받을 수 있는지 등의 규격을 말합니다.
- 프로그램에게 자신이 제공하고자 하는 데이터나 기능을 제어할 수 있는 API로 만들면, 서버와 데이터베이스에 대한 접근 권한이 있는 사람들에게만 접근성 부여할 수 있습니다.
- UI (User Interface)와 비교하면 이해가 편합니다.
- UI: 일반 사용자는 버튼이나 링크, 이미지등 특정 ui를 통해 조작함으로써 시스템을 제어합니다.
- API: 개발자가 특정 프로그램에서 제공하는 규격을 이용하여 응용프로그램을 제어하고 구축합니다.
HTTP API 란?
HTTP란?
- HTTP(Hyper Text Transfer Protocol): HTML(웹문서를 만들기 위한 언어) 문서를 주고 받는데 쓰이는 통신프로토콜(통신규약)이며, TCP 와 UDP 를 사용하여 통신하며 80번 포트를 사용하는 통신프로토콜(통신규약)입니다.
- HTTPS: Secure HTTP - 보안요소가 추가된 것입니다.
- TCP / IP 를 이용한 응용프로토콜( 응용계층에 위치하고 있어서 )
- HTTP(S) 는 연결상태를 유지하지 않는 비연결성 프로토콜(클라이언트의 이전 상태, 요청등을 기억하지 않음)
- Cookie, Session 등을 도입하여 유지(Cookie - 클라이언트, Session - 클라이언트 상태 in server)
HTTP API 란?
- HTTP를 사용하여 프로그램끼리 소통하는 API를 말합니다.
- 흔히 보는 OPEN API, facebook API, kakao API 등의 대부분 API는 HTTP라는 통신 규칙으로 소통하는 API입니다.
- 그렇다면 HTTP를 사용하지 않는 것도 있나요?
- 미세먼지 측정기와 스마트 창문이 IoT 애플리케이션과 통신(소통)할 수 있는 API가 있어야 합니다.
- 이때 사용하는 소통 방법은 HTTP통신이 아닌 저사양/저전력 환경에 적합한 MQTT, CoAP프로콜을 사용해야 합니다.
HTTP Method
- GET : 지정된 URL에서 리소스의 표현을 조회
- POST : 지정된 URL에 신규 리소스를 생성
- PUT : 지정된 URL에 리소스를 생성하거나 업데이트
- PATCH : 리소스의 부분 업데이트
- DELETE : 지정된 URL의 리소스를 제거
RESTful API란?
RESTful API 란?
- 도입
- 로이 필딩(Roy Fielding)의 2000년 박사학위 논문에서 소개되었으며,
- 로이 필딩은 HTTP의 주요 저자 중 한 사람으로 그 당시 웹(HTTP) 설계의 우수성에 비해 제대로 사용되어지지 못하는 모습에 안타까워하며 HTTP의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표했습니다.
- 정의
- REST?
- REpresentational State Trasfer의 약어로 웹을 이용할 때 제약 조건들을 정의하는 소프트웨어 아키텍처 스타일입니다.
- RESTful?
- REST API의 설계 규칙을 올바르게 지킨 시스템을 RESTful하다 말할 수 있습니다.
- RESTful API?
- 하단의 '규약'을 바탕으로 리소스 중심으로 설계하고 기능에 맞게 HTTP Method 사용하여 설계된 API입니다.
- REST?
- 규약
- HTTP URL/URI을 통해 자원(Resource)을 명시하고,
- HTTP Method(GET, POST, PUT, DELETE)를 통해
- 해당 자원(URL)에 대한 CRUD(Create, Read, Update, Delete)를 적용하는 것을 의미합니다.
- 한마디로 URI로 자원을 표현하는 데에 집중하고, 자원의 상태(행위)에 대한 정의는 HTTP METHOD로 하는 것이 REST한 API를 설계하는 중심 규칙입니다.
CRUD Operation
- Create : 데이터 생성(POST)
- Read : 데이터 조회(GET)
- Update : 데이터 수정(PUT)
- Delete : 데이터 삭제(DELETE)
+ HTTP API vs RESTful API
HTTP API와 REST API는 사실 거의 같은 의미로 사용하고 있으며, 정확한 차이점으로 REST API는 HTTP 프로토콜을 따르면서 아래의 4가지 가이드 원칙을 지켜야 합니다.
- 자원의 식별
- 메세지를 통한 리소스 조작
- 자기서술적 메세지
- 애플리케이션의 상태에 대한 엔진으로서 하이퍼미디어(HATEOAS)
REST 특징: REST 아키텍처에 적용되는 6가지 제한 조건
- Uniform Interface(인터페이스 일관성) :
- URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 말하며,
- 일관적인 인터페이스로 분리되어야 합니다.
- Stateless(무상태) :
- 각 요청 간 클라이언트의 context, 세션과 같은 작업을 위한 상태 정보를 서버에 저장하고 관리하지 않습니다.
- 세션 정보나 쿠키정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 들어오는 요청만을 단순히 처리하면 됩니다.
- 때문에 서비스의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순해집니다.
- Cacheable(캐시 처리 가능) :
- REST의 가장 큰 특징 중 하나는 HTTP라는 기존 웹표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 활용이 가능하여 HTTP가 가진 캐싱 기능이 적용 가능합니다.
- HTTP 프로토콜 표준에서 사용하는 Last-Modified태그나 E-Tag를 이용하면 캐싱 구현이 가능합니다.
- 클라이언트는 응답을 캐싱할 수 있어야 합니다. 캐시를 통해 대량의 요청을 효율적으로 처리할 수 있습니다.
- REST의 가장 큰 특징 중 하나는 HTTP라는 기존 웹표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 활용이 가능하여 HTTP가 가진 캐싱 기능이 적용 가능합니다.
- Self-descriptiveness (자체 표현 구조): Code on demand
- REST API 메시지만 보고도 이를 쉽게 이해 할 수 있는 자체 표현 구조로 되어 있으며,
- 자바 애플릿이나 자바스크립트의 제공을 통해 서버가 클라이언트를 실행시킬 수 있는 로직을 전송하여 기능을 확장시킬 수 있습니다.
- Client/Server(클라이언트/서버) 구조 :
- REST 서버는 API 제공, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보)등을 직접 관리하는 구조로 각각의 역할이 확실히 구분되기 때문에 아키텍처를 단순화시키고 작은 단위로 분리할 수 있습니다.
- 따라서 클라이언트-서버의 각 파트가 독립적으로 구분되어 개발해야할 내용이 명확해지고 서로 간의 의존성을 줄입니다.
- 계층화 :
- REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 합니다.
- 이를 통해 클라이언트는 대상 서버에 직접 연결되어있는지, Proxy를 통해서 연결되었는지 알 수 없습니다.
REST의 장단점
장점
- HTTP 프로토콜의 인프라를 그대로 사용하므로 REST API 사용을 위한 별도의 인프라를 구출할 필요가 없다.
- HTTP 프로토콜의 표준을 최대한 활용하여 여러 추가적인 장점을 함께 가져갈 수 있게 해 준다.
- HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.
- Hypermedia API의 기본을 충실히 지키면서 범용성을 보장한다.
- REST API 메시지가 의도하는 바를 명확하게 나타내므로 의도하는 바를 쉽게 파악할 수 있다.
- 여러 가지 서비스 디자인에서 생길 수 있는 문제를 최소화한다.
- 서버와 클라이언트의 역할을 명확하게 분리한다.
단점
- 표준이 자체가 존재하지 않아 정의가 필요하다.
- 사용할 수 있는 메소드가 4가지밖에 없다.
- HTTP Method 형태가 제한적이다.
- 브라우저를 통해 테스트할 일이 많은 서비스라면 쉽게 고칠 수 있는 URL보다 Header 정보의 값을 처리해야 하므로 전문성이 요구된다.
- 구형 브라우저에서 호환이 되지 않아 지원해주지 못하는 동작이 많다.(익스폴로어)
REST 구성요소
REST API 구성
REST는 다음과 같은 3가지로 구성되어 있습니다.
- 자원(Resource) : HTTP URL
- 자원에 대한 행위 : HTTP Method
- 자원에 대한 표현(Representations)
REST API 설계 규칙 및 예시
1. 소문자를 사용한다.
❌ http://cocoon1787.tistory.com/users/Post-Comments
⭕ http://cocoon1787.tistory.com/users/post-comments
- 대문자는 때로 문제를 일으키는 경우가 있기 때문에 소문자로 작성합니다.
2. 언더바( _ ) 대신 하이픈( - )을 사용한다.
❌ http://cocoon1787.tistory.com/users/post_comments
⭕ http://cocoon1787.tistory.com/users/post-comments
- 정확한 의미나 단어 결합이 불가피한 경우, 가독성을 위해 언더바("_")가 아닌 하이픈("-")을 사용하며,
- 하이픈("-") 사용도 최소한으로 설계합니다.
3. 마지막에 슬래시를 포함하지 않는다.
❌ http://cocoon1787.tistory.com/users/
⭕ http://cocoon1787.tistory.com/users
- 슬래시("/")는 계층 관계를 나타낼 때 사용됩니다.
4. 행위를 포함하지 않는다.
❌ POST http://cocoon1787.tistory.com/users/post/1
⭕ DELETE http://cocoon1787.tistory.com/users/1
- 자원에 대한 행위는 HTTP Method로 표현합니다.(GET, POST, DELETE, PUT)
5. 파일 확장자는 URL에 포함시키지 않는다.
❌ http://cocoon1787.tistory.com/users/photo.jpg
⭕ GET http://cocoon1787.tistory.com/users/photo
HTTP/1.1 Host: cocoon1787.tistory.com Accept: image/jpg
- URL에 메시지 body 내용의 포맷을 나타내기 위한 파일 확장자를 적지 않습니다. 대신 Accept header를 사용합니다.
6. 자원에는 형용사/동사가 아닌 명사를 사용하며, 컨트롤 자원을 의미하는 경우 예외적으로 동사를 사용한다.
❌ http://cocoon1787.tistory.com/duplicating
⭕ http://cocoon1787.tistory.com/duplicate
- URL은 자원을 표현하는데 중점을 두기 때문에 동사, 형용사보다는 명사를 사용하여야 합니다.
리소스 간의 관계를 표현하는 방법
REST 리소스 간에는 연관 관계가 있을 수 있고, 이런 경우 다음과 같은 표현방법으로 사용합니다.
/리소스명/리소스 ID/관계가 있는 다른 리소스명
ex) GET : /users/{userid}/devices (일반적으로 소유 ‘has’의 관계를 표현할 때)
만약에 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현하는 방법이 있습니다. 예를 들어 사용자가 ‘좋아하는’ 디바이스 목록을 표현해야 할 경우 다음과 같은 형태로 사용될 수 있습니다.
GET : /users/{userid}/likes/devices (관계명이 애매하거나 구체적 표현이 필요할 때)
자원을 표현하는 Colllection과 Document
Collection과 Document에 대해 알면 URI 설계가 한 층 더 쉬워집니다. DOCUMENT는 단순히 문서로 이해해도 되고, 한 객체라고 이해하셔도 될 것 같습니다. 컬렉션은 문서들의 집합, 객체들의 집합이라고 생각하시면 이해하시는데 좀더 편하실 것 같습니다. 컬렉션과 도큐먼트는 모두 리소스라고 표현할 수 있으며 URI에 표현됩니다. 예를 살펴보도록 하겠습니다.
http://restapi.example.com/sports/soccer
위 URI를 보시면 sports라는 컬렉션과 soccer라는 도큐먼트로 표현되고 있다고 생각하면 됩니다. 좀 더 예를 들어보자면
http://restapi.example.com/sports/soccer/players/13
sports, players 컬렉션과 soccer, 13(13번인 선수)를 의미하는 도큐먼트로 URI가 이루어지게 됩니다. 여기서 중요한 점은 컬렉션은 복수로 사용하고 있다는 점입니다. 좀 더 직관적인 REST API를 위해서는 컬렉션과 도큐먼트를 사용할 때 단수 복수도 지켜준다면 좀 더 이해하기 쉬운 URI를 설계할 수 있습니다.
HTTP 응답 상태 코드
상태코드
200 | 클라이언트의 요청을 정상적으로 수행함 |
201 | 클라이언트가 어떠한 리소스 생성을 요청, 해당 리소스가 성공적으로 생성됨(POST를 통한 리소스 생성 작업 시) |
400 | 클라이언트의 요청이 부적절 할 경우 사용하는 응답 코드 |
401 | 클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 때 사용하는 응답 코드 (로그인 하지 않은 유저가 로그인 했을 때, 요청 가능한 리소스를 요청했을 때) |
403 | 유저 인증상태와 관계 없이 응답하고 싶지 않은 리소스를 클라이언트가 요청했을 때 사용하는 응답 코드 (403 보다는 400이나 404를 사용할 것을 권고. 403 자체가 리소스가 존재한다는 뜻이기 때문에) |
405 | 클라이언트가 요청한 리소스에서는 사용 불가능한 Method를 이용했을 경우 사용하는 응답 코드 |
301 | 클라이언트가 요청한 리소스에 대한 URI가 변경 되었을 때 사용하는 응답 코드 (응답 시 Location header에 변경된 URI를 적어 줘야 합니다.) |
500 | 서버에 문제가 있을 경우 사용하는 응답 코드 |
- 잘 설계된 REST API는 URI만 잘 설계된 것이 아닌 그 리소스에 대한 응답을 잘 내어주는 것까지 포함되어야 합니다.
- 정확한 응답의 상태코드만으로도 많은 정보를 전달할 수가 있기 때문에 응답의 상태코드 값을 명확히 돌려주는 것도 중요한 일입니다.
참고
- 서버 API 통신과 REST API: https://velog.io/@blackb0x/%EC%84%9C%EB%B2%84-API-%ED%86%B5%EC%8B%A0%EA%B3%BC-REST-API
- [Network] REST란? REST API란? RESTful이란?: https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html
- API, HTTP API, REST API 차이: https://bentist.tistory.com/37
- REST API 제대로 알고 사용하기: https://meetup.toast.com/posts/92
'Study: ComputerScience(CS) > CS: Network' 카테고리의 다른 글
[Network] Socket 소켓 프로그래밍 (feat. sockaddr_in, IPv4...) (2) | 2022.12.16 |
---|---|
[Network] Message Queue(메시지큐) 정리 (0) | 2022.11.26 |
[Network] 네트워크 기본 개념 정리 (IP, Route, Subnet...) (1) | 2022.10.08 |
[Network] Blocking vs Non-Blocking & Sync vs Async 비교 정리 (0) | 2022.09.25 |
[Network] HTTP vs HTTPS / GET vs POST 차이점 비교 (0) | 2022.07.19 |