API란?
- Application Programming Interface의 약자.
- 프로그램을 실행하는 인터페이스.
- 프로그램이 다른 프로그램과 상호작용하기 위한 규약이다.
- 프로그램에 요청을 전달하기 위한 통로 혹은 방법으로 생각하면 된다.
REST란?
- Representational State Transfer의 약자.
- 웹 애플리케이션을 개발하기 위한 아키텍처 스타일 중 하나.
- 클라이언트와 서버 간의 '통신 방식'을 규정한 것.
- HTTP 프로토콜을 기반으로 하며 자원, 행위, 표현 세 가지 요소로 구성된다.
자원(Resource): URI
행위(Verb): HTTP Method
표현(Representations)
REST API란?
REST 아키텍처 스타일에 따라 구성한 API를 의미한다.
RESTful API란?
HTTP를 위한 아키텔처 스타일 중 하나로 REST 원칙을 따르는 웹 서비스를 구현하는 방식이다.
클라이언트와 서버 간 자원을 주고받을 때 일관적인 방식을 제공하며 이를 통해 서버와 클라이언트의 역할을 명확하게 분리하고 서로 독립적으로 개발할 수 있게 한다.
REST API와 RESTful API의 차이점
REST API는 REST 아키텍처 스타일을 따르는 API이고, RESTful API는 REST API를 제공하는 웹 서비스를 의미한다
RESTful API에서 HTTP Method(행위)
대표적으로는 GET, POST, PUT, DELETE가 있다.
CRUD에서 보통 다음과 같이 사용한다.
- GET: 조회, URI로 지정된 정보를 검색한다.
- POST: 등록, URI로 지정된 위치에 새로운 자원을 생성한다.
- PUT: 수정, URI로 지정된 위치의 자원을 갱신한다.
- DELETE: 삭제, URI로 지정된 위치의 자원을 삭제한다.
전체 메소드는 총 8개로 다음과 같다.
- GET: 서버로부터 데이터를 취득
- POST: 서버에 데이터를 추가, 작성 등
- PUT: 서버의 데이터를 갱신, 작성 등
- DELETE: 서버의 데이터를 삭제
- HEAD: 서버 리소스의 헤더(메타 데이터 취득)
- OPTIONS: 리소스가 지원하는 메소드 취득
- PATCH: 리소스의 일부분을 수정
- CONNECT: 프록시 동작의 터널 접속 변경
PUT과 PATCH의 차이점
PUT 메소드는 전체 리소스를 교체하는 데 사용되고, PATCH 메소드는 일부 리소스를 수정한다는 데 사용된다.
설계 예시
:id와 같이 변하는 값은 하나의 특정 resource를 나타내는 고유값이어야 한다.
RESTful API 디자인 가이드
RESTful API 설계 시 가장 중요한 항목은 다음 두가지이다.
- URI는 정보의 자원을 표현한다.
- 자원에 대한 행위는 HTTP Method로 표현한다.
자원이란?
Resource.
웹 상에 존재하는 데이터나 정보와 같은 것을 의미한다.
사용자, 글, 댓글, 이미지 등이 모두 자원이다.
URI 설계 시 주의할 점
1) 슬래시 구분자(/)는 계층 관계를 나타나는 데 사용한다.
http://restapi.example.com/houses/apartments
http://restapi.example.com/animals/mammals/whales
2) URI 마지막 문자로 슬래시(/)를 포함하지 않는다.
URI에 포함되는 모든 글자는 리소스의 유일한 식별자로 사용되어야 한다.
URI가 다르다는 것은 리소스가 다르다는 것이고, 역으로 리소스가 다르면 URI도 달라져야 한다.
RESTful API는 분명한 URI를 만들어 통신하기 때문에 혼동을 주지 않도록 URI 경로의 마지막에는 슬래시(/)를 사용하지 않는다.
http://restapi.example.com/houses/apartments/ (X)
http://restapi.example.com/houses/apartments (0)
3) 하이픈(-)은 URI 가독성을 높이기 위해 사용한다.
긴 URI 경로를 사용하게 되면 하이픈을 사용해 가독성을 높일 수 있다.
4) 밑줄(_)은 URI에 사용하지 않는다.
밑줄은 알아보기 어렵거나 글자를 가리기도 한다.
가독성을 위해 밑줄보다는 하이픈(-)을 사용하는 것이 좋다.
5) URI 경로에는 소문자가 적합하다.
URI 경로에 대문자 사용은 피해야 한다. 대소문자에 따라 다른 리소스로 인식되기 때문이다.
6) 파일 확장자는 URI에 포함시키지 않는다.
RESTful API에서는 메세지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다.
Accept header를 사용하자.
GET /members/soccer/345/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg
RESTful API 상태 코드(Status Code)
RESTful API에서는 HTTP 상태코드를 사용하여 클라이언트에게 요청의 성공 또는 실패를 알려준다.
상태코드는 3자리 숫자로 표현되며, 각각의 숫자는 특정한 의미를 가지고 있다.
전체적인 상태코드 형태
| 상태코드 | 상태 정보 | 의미 |
| 1xx | Informational | 요청이 수신되었으며 처리가 계속됨을 의미한다. |
| 2xx | Success | 요청이 성공적으로 처리되었음을 의미한다. |
| 3xx | Redirection | 요청이 완료되기 위해 추가 작업이 필요함을 의미한다. |
| 4xx | Client Error | 클라이언트 오류로 인해 요청이 실패함을 의미한다. |
| 5xx | Server Error | 서버 오류로 인해 요청이 실패함을 의미한다. |
일반적으로 사용되는 상태코드
| 상태코드 | 상태 정보 | 의미 |
| 200 | OK | 요청이 성공적으로 처리되었음을 의미한다. 클라이언트에게 요청한 데이터를 반환합니다. |
| 201 | Created | 새로운 리소스가 성공적으로 생성되었음을 의미한다. |
| 204 | No Content | 요청이 성공적으로 처리되었지만, 반환할 데이터가 없음을 의미한다. |
| 400 | Bad Request | 클라이언트 요청이 잘못되었음을 의미한다. 요청이 잘못된 경우에는 이 상태코드를 반환합니다. |
| 401 | Unauthorized | 클라이언트가 인증되지 않았음을 의미한다. |
| 403 | Forbidden | 클라이언트가 요청한 리소스에 접근할 권한이 없음을 의미한다. |
| 404 | Not Found | 요청한 리소스를 찾을 수 없음을 의미한다. |
| 500 | Internal Server Error | 서버에서 오류가 발생하여 요청을 처리할 수 없음을 의미한다. |
API 문서화
RESTful API를 사용하는 개발자들이 API를 쉽게 이해하고 사용할 수 있도록 문서화가 필요하다.
API 문서는 API URL, 자원(Resource), 행위(Verb)/HTTP Method, 표현(Representation), 상태코드, 응답 형태 등을 상세히 기술해야 한다.
1) API Endpoint 정의하기
API Endpoint란?
클라이언트가 서버에게 요청을 보내 통신하는 URL.
HTTP Method(GET, POST, PUT, DELETE 등)와 함께 사용된다.
| 고려 사항 | 설명 |
| URL 구조 | 일관성 있는 URL 구조를 유지해야 합니다. |
| HTTP Method | 각 Endpoint에 대해 지원하는 HTTP Method(GET, POST, PUT, DELETE 등)을 정의해야 합니다. |
| Request와 Response 포맷 | Request와 Response의 데이터 형식(JSON, XML, CSV 등)을 정의해야 합니다. |
2) API Endpoint 문서화하기
| 번호 | 문서화 포함 내용 |
| 1 | Endpoint의 URL과 HTTP Method |
| 2 | Endpoint의 기능과 목적 |
| 3 | 요청(Request)과 응답(Response)의 데이터 형식 |
| 4 | Request와 Response의 필수/선택적 매개변수 및 예시 |
| 5 | 에러 메시지와 상태 코드 |
3) API 문서화 도구 사용
Swagger, Postman, Apiary 등의 도구를 사용하여 Endpoint 정의와 문서화를 쉽게 해결할 수 있다.
참고한 글
https://adjh54.tistory.com/150
https://velog.io/@yh20studio/CS-Http-Method-%EB%9E%80-GET-POST-PUT-DELETE